# beagle cheatsheet

What the language can do, with verified examples. Generated by
`bin/beagle-cheatsheet` from beagle-lib/private/cheatsheet.rkt; every
example is parse+type-checked by the test suite, so nothing here is stale.

Files begin with `#lang beagle`, then `(ns ...)`, `(define-mode strict)`,
and `(define-target clj | js | nix | odin)`. For signatures, fields,
and the full form set, query the compiler (`bin/beagle sig|fields|syntax`,
or `bin/beagle` for all commands).

## Types

### defrecord
Product type with typed fields; generates a constructor and accessors.

```clojure
(defrecord Point [x :- Int y :- Int])
```

### defunion + match
Sum type over records. `match` is checked EXHAUSTIVELY — a missing constructor is a compile error (and the repair loop can auto-fill the clauses).

```clojure
(defrecord Circle [r :- Int])
(defrecord Square [side :- Int])
(defunion Shape Circle Square)
(defn area [s :- Shape] :- Int
  (match s [(Circle r) r] [(Square side) side]))
```

### defenum
Enumeration of named constants.

```clojure
(defenum Color Red Green Blue)
```

### inline :- annotations
Types attach inline with `:-` on params, returns, defs, and let bindings. (`(name : T)` pairs also parse.)

```clojure
(defn clamp [n :- Int] :- Int (if (> n 100) 100 n))
```


## Types / contracts

### defscalar :where
Refinement contract: a base type narrowed by predicates. Literal violations are caught statically; non-literal values get a runtime guard emitted per target (nix `assert`, clj `:pre`, js `throw`).

```clojure
(defscalar Percentage Int :where (>= 0) (<= 100))
(def half :- Percentage (->Percentage 50))
```


## Bindings

### def / defonce
Typed top-level binding.

```clojure
(def answer :- Int 42)
```


## Functions

### defn
Function with typed params and return. Params are a bracket vector.

```clojure
(defn add [x :- Int y :- Int] :- Int (+ x y))
```


## Control flow

### let / loop / recur / cond
Standard control flow; bindings use bracket vectors.

```clojure
(defn sum-to [n :- Int] :- Int
  (loop [i 0 acc 0]
    (cond [(> i n) acc]
          [:else (recur (+ i 1) (+ acc i))])))
```


## Macros

### defmacro + quasiquote
Hygienic macros. Quasiquote `` ` ``, unquote `~`, splice `~@`. Free references resolve at the macro's definition site (mode-2 hygiene).

```clojure
(defmacro twice [x] `(do ~x ~x))
```


## Interop

### declare-extern
Declare a host function/value with a type so typed code can call into the target runtime.

```clojure
(declare-extern host/now [-> Int])
```

