API Reference

Special Forms

These are primitive language constructs handled by the compiler.

def

Define a var in the current namespace.

(def x 42)
(def greeting "hello")

if

Conditional evaluation. Only evaluates the chosen branch.

(if (> x 0) "positive" "non-positive")

do

Evaluate expressions sequentially, return the last.

(do (println "hello") (println "world") 42)  ;=> 42

fn

Create an anonymous function. Optionally named for self-recursion.

(fn [x y] (+ x y))
(fn factorial [n] (if (< n 2) 1 (* n (factorial (- n 1)))))

let*

Lexical bindings (primitive form — prefer let macro).

(let* [x 10 y 20] (+ x y))  ;=> 30

quote

Prevent evaluation. Reader shorthand: 'form.

(quote (1 2 3))  ;=> (1 2 3)
'foo              ;=> foo

loop / recur

Structured tail-recursive iteration.

(loop [i 0 acc 0]
  (if (< i 10) (recur (+ i 1) (+ acc i)) acc))  ;=> 45

try / catch / finally / throw

Exception handling. Only maps can be thrown.

(try
  (throw {:type :oops :msg "bad"})
  (catch e (println (:msg e)))
  (finally (println "done")))

defmacro

Define a macro.

(defmacro unless [test & body]
  `(if (not ~test) (do ~@body)))

spawn

Create a new cooperative task.

(def t (spawn (+ 1 2)))
(await t)  ;=> 3

yield

Yield control to the scheduler.

(yield)

await

Wait for a task to complete and return its result.

(await (spawn (+ 1 2)))  ;=> 3

>! / <!

Send to / receive from a channel. Blocks the task if needed.

(def ch (chan 1))
(>! ch 42)
(<! ch)  ;=> 42

Callable Non-Functions

Keywords, hash maps, and vectors can be used in head (call) position, like Clojure's IFn:

;; Keyword as map lookup (1-2 args)
(:foo {:foo 42})          ;=> 42
(:missing {:a 1} "nope")  ;=> "nope"

;; Map as lookup function (1-2 args)
({:a 1 :b 2} :b)          ;=> 2
({:a 1} :missing "nope")   ;=> "nope"

;; Vector as index function (1 arg)
([10 20 30] 1)             ;=> 20

;; Works dynamically — keyword bound to a variable
(let [k :name] (k {:name "alice"}))  ;=> "alice"

;; Useful as higher-order functions
(map :age [{:age 30} {:age 25}])     ;=> (30 25)

Native Functions

Arithmetic

All arithmetic supports fixnum, bigint, and float with automatic promotion.

Comparison

Collections

Type Predicates

String Functions

Strings also work as sequences with first, rest, nth, count, empty?, and map.

I/O

spit supports :append true: (spit "f.txt" "more" :append true)

Utility

Concurrency

Use special forms >!, <!, spawn, await, yield for task/channel operations.

Atoms

Metadata

defn and defmacro support an optional docstring after the name:

(defn greet "Greet a person by name." [name] (str "Hello, " name))
(doc greet)
;; -------------------------
;; greet
;;   Greet a person by name.
;; -------------------------

Module Libraries

Tar Archives (beer.tar)

(require 'beer.tar :as 'tar)

Shell Execution (beer.shell)

(require 'beer.shell :as 'shell)

TCP Sockets (beer.tcp)

(require 'beer.tcp :as 'tcp)

UDP Sockets (beer.udp)

(require 'beer.udp :as 'udp)

udp/recv returns {:data string :host string :port int}. Use (close sock) to close.

Echo server example:

(require 'beer.udp :as 'udp)

(defn echo-server [port]
  (let [sock (udp/bind port)]
    (println "UDP echo on port" port)
    (loop []
      (let [pkt (udp/recv sock 65507)]
        (when pkt
          (udp/send sock (:host pkt) (:port pkt) (:data pkt))
          (recur))))))

(spawn (echo-server 9999))

Network REPL (beer.nrepl)

(require 'beer.nrepl)
(beer.nrepl/start! 7888)

Embeds a structured TCP REPL server into any running beerlang process. The protocol is EDN map messages, one per line, inspired by Clojure's nREPL. Multiple concurrent clients are supported.

Protocol:

Client → server   {:op "eval" :code "(+ 1 2)" :id "id-1"}
Server → client   {:id "id-1" :value "3"}
                  {:id "id-1" :status "done"}

Supported ops:

From the terminal:

printf '{"op" "eval" "code" "(+ 1 2)" "id" "1"}\n' | nc localhost 7888
# → {:id "1" :value "3"}
# → {:id "1" :status "done"}

Emacs integration (requires beerlang-repl.el):

Simple eval REPL (beer.nrepl.simple)

A minimal eval-over-TCP server for nc/telnet — send a form, get a result back.

(require 'beer.nrepl.simple)
(beer.nrepl.simple/start! 7889)

$ nc localhost 7889
(+ 1 2)
3
(map inc [1 2 3])
(2 3 4)

Both servers can run simultaneously — beer.nrepl on 7888 for Emacs, beer.nrepl.simple on 7889 for quick nc access.

JSON (beer.json)

(require 'beer.json :as 'json)

HTTP Server (beer.http)

(require 'beer.http :as 'http)

The handler receives {:method :path :headers :body} and returns {:status :headers :body}.

Actor System (beer.hive)

(require 'beer.hive :as 'hive)

Actor handlers receive (state msg) and return {:state new-state} or {:state s :reply val} for ask. Pass {:name :some-name} in opts to register the actor.

Standard Library (lib/core.beer)

Macros

Numeric

Function Utilities

Sequence Functions

Map Functions

Sorting and Dedup

Exception Helpers

Special Vars

Bytecode Metaprogramming

disasm and asm expose the VM's bytecode representation as plain beerlang data, enabling inspection, transformation, and hand-crafted code generation.

disasm

Decompile a bytecode function into a data map:

(defn square [x] (* x x))
(disasm square)
;=> {:arity 1
;    :constants [*]
;    :code [[:ENTER 1] [:LOAD_LOCAL 0] [:LOAD_LOCAL 0]
;           [:LOAD_VAR 0] [:TAIL_CALL 2] [:RETURN]]}

• :arity — number of fixed parameters (-1 for variadic)
• :constants — constant pool (values referenced by index in :code)
• :code — vector of [opcode-keyword operand ...] tuples

asm

Assemble a data map back into a callable function:

(def sq (asm (disasm (fn [x] (* x x)))))
(sq 7)   ;=> 49

The map must have :code, :constants, and :arity. Round-tripping (asm (disasm f)) produces an equivalent function.

Use cases

;; Inspect what the compiler generates
(disasm (fn [x] (if (> x 0) x (- x))))

;; Transform a function's bytecode
(let [d (disasm my-fn)]
  (asm (assoc d :code (transform (:code d)))))

C Foreign Function Interface (beer.ffi)

Requires make CFFI=1 at build time (links -lffi). Without it, beer.ffi is not registered.

(ns myscript (:require [beer.ffi :as ffi]))

Low-level primitives

Type keywords for ffi/call, ffi/cget, ffi/cset!:

High-level macros

Use these with the ffi/ alias (they live in beer.ffi, not beer.core).

ffi/def-cfn — bind a C function by name:

(ffi/def-cfn sqrt "m" "sqrt" [:double] :double)
(sqrt 2.0)   ;=> 1.41421...

Args: fn-name lib-short-name c-symbol arg-types ret-type

ffi/def-cstruct — name a struct descriptor map:

(ffi/def-cstruct Point {:size 16
                        :fields [{:name :x :type :double :offset 0}
                                 {:name :y :type :double :offset 8}]})

ffi/def-cstruct-accessors — generate helpers from a named struct:

(ffi/def-cstruct-accessors Point)
;; generates: point-x  set-point-x!  point-y  set-point-y!  point-alloc  point-size
(def p (point-alloc))
(set-point-x! p 3.0)
(point-x p)   ;=> 3.0
(ffi/free p)

ffi/load-bindings — install all fns and structs from a binding map:

(def libm (read-string (slurp "bindings/libm.beer")))
(ffi/load-bindings libm)
;; all :fns and :structs are now defined in the current namespace

Also accepts a literal map: (ffi/load-bindings {:fns [...] :structs []}).

Library utilities

Probe generator (beer.ffi.probe)

(ns myscript (:require [beer.ffi.probe :as probe]))

Spec map keys: :headers (list of #include names), :structs (list of {:name :fields}), :fns (verbatim function descriptors), :cc (compiler, default "cc"), :cflags (extra flags), :library, :version (for :meta).

Binding file format:

{:meta    {:library "zlib" :version "1.3.1" :abi "arm64-darwin" :cc "cc" ...}
 :fns     [{:name "compress" :lib "z" :sym "compress" :args [...] :ret :int32} ...]
 :structs {"arm64-darwin" [{:name "z_stream" :size 112 :fields [...]}]}}

:structs is keyed by ABI string, so a single binding file can cover multiple platforms.

beer-probe CLI:

beer-probe spec.beer bindings/libz.beer   # write binding file
beer-probe spec.beer                       # print measured layouts to stdout

Testing (beer.test)

(require 'beer.test :as 't)