HQL Language Syntax Reference

// Single-line comment
/* Multi-line
   block comment */
;; Lisp-style comment (convention in .hql files)
#!/usr/bin/env hlvm   // Shebang line (ignored)

foo              // Simple
my-function      // Kebab-case (preferred)
MyClass          // PascalCase (classes)
foo?             // Predicate
foo!             // Mutating
*global*         // Earmuffs (dynamic vars)
_private         // Private convention

fn let var const def if cond when unless do
loop recur for for-of for-await-of while repeat
class new async await return throw try catch finally
import export macro match switch case default
=> & _ nil true false this
label break continue yield yield*
fn* async-fn* getter setter static
type deftype interface abstract-class namespace
const-enum declare fn-overload

// Numbers
42                // Integer
3.14159           // Float
-17               // Negative
1e10              // Scientific
123n              // BigInt

// Strings
"hello"           // Double-quoted
"line1\nline2"    // Escape sequences
`template ${x}`   // Template literal

// Booleans
true
false

// Null
nil               // null/undefined

// Vector (Array)
[1 2 3]           // No commas
[1, 2, 3]         // JSON style

// Hash-map (Object)
{name: "Alice" age: 30}
{"name": "Alice", "age": 30}

// Set
#[1 2 3]

// Nested
{user: {name: "Bob" tags: ["admin" "user"]}}

(get arr 0)           // arr[0]
(get arr 0 "default") // with default
(get obj "name")      // obj.name
obj.name              // Dot notation
(first [1 2 3])       // → 1
(rest [1 2 3])        // → [2 3]
(nth [1 2 3] 1)       // → 2

(let x 10)
(= x 20)              // Reassignment allowed

// Multiple bindings with body
(let (x 10 y 20)
  (= x 100)
  (+ x y))            // → 120

(const PI 3.14159)
(def PI 3.14159)       // def is an alias for const
// (= PI 3.0)          ERROR: Cannot reassign const

// Objects/arrays are frozen (deep immutability)
(const data {"name": "Alice"})
// (= data.name "Bob") ERROR: Cannot mutate frozen object

(var count 0)
(= count (+ count 1)) // Reassign

// Multiple bindings with body
(var (x 10 y 20)
  (= x 100)
  (+ x y))            // → 120

// Array destructuring
(let [a b c] [1 2 3])

// With rest
(let [first & rest] [1 2 3 4])

// Skip elements
(let [a _ c] [1 2 3])

// Object destructuring
(let {name age} person)

// With defaults
(let [x (= 10)] [])   // x = 10 if undefined

// Positional parameters
(fn add [a b]
  (+ a b))

// Map parameters (all must have defaults)
(fn connect {host: "localhost" port: 8080}
  (+ host ":" port))

// ⚠️ CRITICAL: NO SPACE after colon!
(fn add [a:number b:number] :number
  (+ a b))

// Union types
(fn handle [value:string|number] :void
  (print value))

(fn [x] (* x x))
(map (fn [x] (* x 2)) [1 2 3])

// Implicit parameters ($0, $1, $2...)
(=> (* $0 2))
(=> (+ $0 $1))
(map (=> (* $0 2)) [1 2 3])

// Property access
(=> $0.name)

// Explicit parameters
(=> [x] (* x x))
(=> [x y] (+ x y))

(async fn fetch-data [url]
  (let response (await (js/fetch url)))
  (await (.json response)))

(fn sum [first & rest]
  (reduce + first rest))

// Named multi-arity function
(fn greet
  ([] "Hello!")
  ([name] (+ "Hello, " name "!"))
  ([first last] (+ "Hello, " first " " last "!")))

(greet)           // → "Hello!"
(greet "Alice")   // → "Hello, Alice!"
(greet "Alice" "Smith") // → "Hello, Alice Smith!"

// Anonymous multi-arity
(let handler (fn
  ([] (handle-empty))
  ([x] (handle-one x))
  ([x y] (handle-two x y))))

// Multi-arity with rest parameters (catch-all)
(fn variadic
  ([x] (+ "one: " x))
  ([x y & more] (+ "two+: " x " " y " " (vec more))))

// Async multi-arity
(async fn fetch-data
  ([url] (await (fetch-data url {})))
  ([url opts] (await (js/fetch url opts))))

// Generator multi-arity
(fn* range-gen
  ([end] (yield* (range-gen 0 end)))
  ([start end]
    (var i start)
    (while (< i end)
      (yield i)
      (= i (+ i 1)))))

// Declare a function as pure (compile-time enforcement)
(fx pure-add [a b]
  (+ a b))

// Pure functions cannot contain:
// - Calls to impure functions
// - Mutations (push, pop, etc.)
// - Side effects (console.log, fetch, etc.)
// - Generators (yield)
// See docs/features/21-effect-system/spec.md for details

// Implicit return (last expression)
(fn double [x]
  (* x 2))

// Explicit return
(fn safe-divide [a b]
  (if (=== b 0)
    (return 0))
  (/ a b))

(class Person
  (var name "")
  (var age 0)

  (constructor [name age]
    (do
      (= this.name name)
      (= this.age age)))

  (fn greet []
    (+ "Hello, " this.name)))

(class Counter
  (static var count 0)
  (static const MAX 100)  // Immutable static field

  (static fn increment []
    (= Counter.count (+ Counter.count 1))))

(class Circle
  (var _radius 0)

  (getter radius []
    this._radius)

  (setter radius [value]
    (when (> value 0)
      (= this._radius value)))

  (getter area []
    (* Math.PI this._radius this._radius)))

(class BankAccount
  (#balance 0)           // Private field
  (#transactions [])

  (fn deposit [amount]
    (= this.#balance (+ this.#balance amount))))

// Class inheritance with extends
(class Animal
  (constructor [name]
    (= this.name name))
  (fn describe []
    (+ "Animal: " this.name)))

(class Dog extends Animal
  (constructor [name breed]
    (super name)
    (= this.breed breed))
  (fn bark []
    "Woof!"))

(let d (new Dog "Rex" "Labrador"))
d.name    // => "Rex" (inherited)
d.breed   // => "Labrador"
(d.bark)  // => "Woof!"

// Abstract class with abstract methods
(abstract-class Animal [
  (abstract-method speak [] :string)
])

(if condition
  then-expr
  else-expr)

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

(cond
  ((< x 0) "negative")
  ((=== x 0) "zero")
  ((> x 0) "positive")
  (else "unknown"))

(when (> x 0)
  (print "positive")
  x)

(unless (=== x 0)
  (/ 100 x))

(switch status
  (case "active" (run))
  (case "waiting" (wait))
  (default (error)))

// With fallthrough
(switch grade
  (case "A" :fallthrough)
  (case "B" (console.log "Good"))
  (default (console.log "Other")))

// String cases
(switch color
  (case "red" (setColor "#ff0000"))
  (case "green" (setColor "#00ff00"))
  (default (setColor "#000000")))

(match value
  (case 1 "one")
  (case 2 "two")
  (default "other"))

// Or-patterns: match multiple values in one case
(match status-code
  (case (| 200 201 204) "success")
  (case (| 400 422) "client error")
  (case (| 500 502 503) "server error")
  (default "unknown"))

// Array patterns
(match point
  (case [0, 0] "origin")
  (case [x, 0] "on x-axis")
  (case [0, y] "on y-axis")
  (case [x, y] "somewhere"))

// Object patterns
(match user
  (case {name: n, age: a} (+ n " is " a))
  (default "Unknown"))

// With guards
(match n
  (case x (if (> x 0)) "positive")
  (case x (if (< x 0)) "negative")
  (default "zero"))

// Wildcard pattern
(match value
  (case _ "anything"))

(do
  (print "step 1")
  (print "step 2")
  (+ 1 2))           // Returns 3

(loop [i 0 sum 0]
  (if (< i 5)
    (recur (+ i 1) (+ sum i))
    sum))             // → 10

// Factorial
(loop [n 5 acc 1]
  (if (<= n 1)
    acc
    (recur (- n 1) (* acc n))))

// Single arg: 0 to n-1
(for [i 3]
  (print i))          // 0, 1, 2

// Two args: start to end-1
(for [i 5 8]
  (print i))          // 5, 6, 7

// Three args: start to end-1 by step
(for [i 0 10 2]
  (print i))          // 0, 2, 4, 6, 8

(for-of [item items]
  (print item))

(for-of [n numbers]
  (when (=== n 0)
    (continue))
  (when (> n 100)
    (break))
  (process n))

(for-await-of [chunk stream]
  (process chunk))

(for-await-of [response responses]
  (const data (await (.json response)))
  (results.push data))

(var count 0)
(while (< count 5)
  (print count)
  (= count (+ count 1)))

(repeat 5
  (print "hello"))

(label outer
  (while true
    (while true
      (when done
        (break outer)))))

(label search
  (for-of [item items]
    (when (matches item)
      (break search))))

// Nested labels
(label outer
  (while (< i n)
    (label inner
      (while (< j m)
        (when found
          (break outer))
        (when skip
          (continue inner))))))

(while (< i 10)
  (= i (+ i 1))
  (when (=== (% i 2) 0)
    (continue))
  (when (> i 50)
    (break))
  (console.log i))

(fn* range [start end]
  (var i start)
  (while (< i end)
    (yield i)
    (= i (+ i 1))))

(fn* fibonacci []
  (var a 0)
  (var b 1)
  (while true
    (yield a)
    (var temp b)
    (= b (+ a b))
    (= a temp)))

(fn* simple []
  (yield 1)
  (yield 2)
  (yield 3))

(fn* combined []
  (yield* [1 2 3])    // Delegate to iterable
  (yield 4))

(async fn* fetchPages [urls]
  (for-of [url urls]
    (yield (await (fetch url)))))

(async fn* paginate [startPage maxPages]
  (var page startPage)
  (while (<= page maxPages)
    (const data (await (fetchPage page)))
    (yield data)
    (= page (+ page 1))))

(type MyString string)
(type ID number)
(type Point {x: number, y: number})

// With generics
(type Container<T> T)
(type Box<T> {value: T})

(type StringOrNumber (| string number))
(type Status (| "pending" "active" "done"))
(type Nullable (| string null undefined))

(type Combined (& A B))
(type AdminUser (& User AdminPermissions))

(type PersonKeys (keyof Person))
(type Keys<T> (keyof T))

(type NameType (indexed Person "name"))     // Person["name"]
(type Value<T> (indexed T (keyof T)))       // T[keyof T]

(type IsString<T> (if-extends T string true false))
// → T extends string ? true : false

(type UnwrapPromise<T> (if-extends T (Promise (infer U)) U T))
// → T extends Promise<infer U> ? U : T

(type Deep<T> (if-extends T string "str" (if-extends T number "num" "other")))

(type MyReadonly<T> (mapped K (keyof T) (indexed T K)))
// → { [K in keyof T]: T[K] }

(type Point (tuple number number))
(type Entry (tuple string number boolean))

// With rest
(type Args (tuple string (rest (array number))))
// → [string, ...number[]]

(type Numbers (array number))
(type MixedArray (array (| string number)))  // → (string | number)[]

(type ImmutableNumbers (readonly (array number)))
// → readonly number[]

(type MyType (typeof myVar))

(type ArrayElement<T> (if-extends T (array (infer E)) E never))

// Array type
[Int]                // → Int[]
[String]             // → String[]

// Dictionary/Map type
[String: Int]        // → Record<string, number>
[String: Any]        // → Record<string, any>

// Tuple type
(Int, String)        // → [Int, String]
(Int, String, Bool)  // → [Int, String, Bool]

(type PartialPerson (Partial Person))
(type RequiredConfig (Required Config))
(type PickedPerson (Pick Person (| "name" "age")))
(type StringRecord (Record string number))

// Any valid TypeScript type expression
(deftype Complex "Record<string, number>")
(deftype EventName "`on${string}`")           // Template literal types
(deftype "Mutable<T>" "{ -readonly [K in keyof T]: T[K] }")

(interface User "{ id: string; name: string }")
(interface Point "{ readonly x: number; readonly y: number }")
(interface Config "{ debug?: boolean; port?: number }")
(interface StringMap "{ [key: string]: string }")

(abstract-class Animal [
  (abstract-method speak [] :string)
])

(abstract-class Container<T> [
  (abstract-method getValue [] :T)
  (abstract-method setValue "value: T" :void)
])

(fn-overload process "x: string" :string)
(fn-overload process "x: number" :number)
(fn-overload "identity<T>" "x: T" :T)

(namespace Utils [
  (deftype ID "string")
])

(namespace Models [
  (interface User "{ id: string; name: string }")
])

(const-enum Direction [North South East West])
(const-enum Status [(OK 200) (NotFound 404) (Error 500)])
(const-enum Color [(Red "red") (Green "green") (Blue "blue")])

(declare function "greet(name: string): string")
(declare var "globalCounter: number")
(declare const "PI: 3.14159")
(declare module "my-module")

(decorator @Injectable)
(decorator (@Component {selector: "app"}))

// ⚠️ NO SPACE after colon!
(fn add [a:number b:number] :number
  (+ a b))

(fn process [items:Array<number> callback:Function]
  (map callback items))

(fn handle [value:string|number] :void
  (print value))

// Mixed typed and untyped (gradual typing)
(fn greet [name:string times]
  (print name times))

(import [foo bar] from "module.hql")
(import utils from "utils.hql")
(import [foo as myFoo] from "module.hql")
(import [readFile] from "node:fs")
(import _ from "npm:lodash")

(import-dynamic "./module.js")
(await (import-dynamic "./utils.ts"))
(import-dynamic modulePath)
(import-dynamic `./modules/${name}.js`)

(export (fn add [a b] (+ a b)))
(export my-function)
(export-default my-value)
(export [foo bar])

(try
  (riskyOperation)
  (catch e
    (console.error e))
  (finally
    (cleanup)))

(throw (new Error "Something went wrong"))

js/console            // console
js/Math               // Math
js/Date               // Date
js/JSON               // JSON

(js/console.log "hello")
(js/Math.floor 3.7)
(js/JSON.stringify obj)

(.toLowerCase str)    // str.toLowerCase()
(.push arr item)      // arr.push(item)
(.map arr callback)   // arr.map(callback)

obj.property
obj.nested.prop
obj?.optionalProp     // Optional chaining

(new Date)
(new Date 2024 0 1)
(new Map)
(new Set [1 2 3])
(new Promise (fn [resolve reject] ...))

(await promise)
(async fn fetch-data []
  (let response (await (js/fetch "/api")))
  (await (.json response)))

(macro unless [condition & body]
  `(if (not ~condition)
    (do ~@body)))

(unless (valid? x)
  (throw (new Error "invalid")))

'(1 2 3)              // Quote
`(a b c)              // Syntax quote
`(1 2 ~x)             // Unquote
`(1 2 ~@rest)         // Unquote-splicing

// Thread-first
(-> 5
    (+ 3)
    (* 2))            // → 16

// Thread-last
(->> [1 2 3 4 5]
     (filter (=> (> $0 2)))
     (map (=> (* $0 2))))

// Thread-as
(as-> {name: "Alice"} user
      user.name
      (str "Hello, " user))

(isNull x)            // x === null
(isUndefined x)       // x === undefined
(isNil x)             // x == null
(isDefined x)         // x !== undefined
(isString x)          // typeof x === "string"
(isNumber x)          // typeof x === "number"
(isBoolean x)         // typeof x === "boolean"
(isFunction x)        // typeof x === "function"
(isArray x)           // Array.isArray(x)
(isObject x)          // typeof x === "object" && x !== null && !Array.isArray(x)

(inc x)               // (+ x 1)
(dec x)               // (- x 1)
(str a b c)           // String concatenation
(print & args)        // console.log
(isEmpty coll)        // Check if empty
(isNil x)             // Check if nil

(+ a b c)             // Addition
(- a b)               // Subtraction
(* a b c)             // Multiplication
(/ a b)               // Division
(% a b)               // Modulo
(** a b)              // Exponentiation

// ⚠️ = is ASSIGNMENT, not comparison!
(== a b)              // Loose equality
(=== a b)             // Strict equality (preferred)
(!= a b)              // Loose inequality
(!== a b)             // Strict inequality
(< a b)               // Less than
(> a b)               // Greater than
(<= a b)              // Less or equal
(>= a b)              // Greater or equal

(and a b c)           // Logical AND
(or a b c)            // Logical OR
(not a)               // Logical NOT

(?? a b)              // Nullish coalescing: a ?? b
obj?.prop             // Optional chaining

(??= x 10)            // x ??= 10
(&&= x (getValue))    // x &&= getValue()
(||= name "default")  // name ||= "default"

(& a b)               // Bitwise AND
(| a b)               // Bitwise OR
(^ a b)               // Bitwise XOR
(~ a)                 // Bitwise NOT
(<< a n)              // Left shift
(>> a n)              // Signed right shift
(>>> a n)             // Unsigned right shift

┌──────────────────┬───────────────────────────────────┬──────────────────────────────┐
│ Category         │ HQL Syntax                        │ JavaScript/TypeScript        │
├──────────────────┼───────────────────────────────────┼──────────────────────────────┤
│ BINDINGS         │                                   │                              │
│ Block mutable    │ (let x 10)                        │ let x = 10                   │
│ Block immutable  │ (const x 10)                      │ const x = 10 (frozen)        │
│ Function mutable │ (var x 10)                        │ var x = 10                   │
│ Assignment       │ (= x 20)                          │ x = 20                       │
│ Destructure      │ (let [a b] arr)                   │ let [a, b] = arr             │
├──────────────────┼───────────────────────────────────┼──────────────────────────────┤
│ FUNCTIONS        │                                   │                              │
│ Named            │ (fn add [a b] (+ a b))            │ function add(a, b) {...}     │
│ Anonymous        │ (fn [x] (* x 2))                  │ function(x) { return x*2 }   │
│ Arrow            │ (=> (* $0 2))                     │ (x) => x * 2                 │
│ Async            │ (async fn f [] ...)               │ async function f() {...}     │
│ Generator        │ (fn* g [] (yield 1))              │ function* g() { yield 1 }    │
│ Async Gen        │ (async fn* g [] ...)              │ async function* g() {...}    │
│ Typed            │ (fn f [a:number] :string ...)     │ function f(a: number): str.. │
├──────────────────┼───────────────────────────────────┼──────────────────────────────┤
│ CLASSES          │                                   │                              │
│ Basic            │ (class Foo (constructor [] ...))  │ class Foo { constructor(){} }│
│ Static           │ (static fn bar [] ...)            │ static bar() {...}           │
│ Getter           │ (getter prop [] ...)              │ get prop() {...}             │
│ Setter           │ (setter prop [v] ...)             │ set prop(v) {...}            │
│ Private          │ (#field 0)                        │ #field = 0                   │
│ Extends          │ (class Bar extends Foo ...)       │ class Bar extends Foo {...}  │
├──────────────────┼───────────────────────────────────┼──────────────────────────────┤
│ CONTROL FLOW     │                                   │                              │
│ If               │ (if cond then else)               │ cond ? then : else           │
│ Switch           │ (switch x (case 1 ...) (default)) │ switch(x) { case 1: ... }    │
│ Cond             │ (cond ((c1) r1) (else r2))        │ c1 ? r1 : r2                 │
│ When             │ (when cond body)                  │ if (cond) { body }           │
├──────────────────┼───────────────────────────────────┼──────────────────────────────┤
│ LOOPS            │                                   │                              │
│ Loop/Recur       │ (loop [i 0] (recur (+ i 1)))      │ while loop (optimized)       │
│ For-Of           │ (for-of [x arr] ...)              │ for (const x of arr) {...}   │
│ For-Await-Of     │ (for-await-of [x iter] ...)       │ for await (const x of i) {}  │
│ While            │ (while cond body)                 │ while (cond) { body }        │
│ Label            │ (label name (while ...))          │ name: while (...) {...}      │
│ Break            │ (break) / (break label)           │ break / break label          │
│ Continue         │ (continue) / (continue label)     │ continue / continue label    │
├──────────────────┼───────────────────────────────────┼──────────────────────────────┤
│ GENERATORS       │                                   │                              │
│ Yield            │ (yield value)                     │ yield value                  │
│ Yield*           │ (yield* iterable)                 │ yield* iterable              │
├──────────────────┼───────────────────────────────────┼──────────────────────────────┤
│ TYPE SYSTEM      │                                   │                              │
│ Type Alias       │ (type Name T)                     │ type Name = T                │
│ Union            │ (| A B C)                         │ A | B | C                    │
│ Intersection     │ (& A B C)                         │ A & B & C                    │
│ Keyof            │ (keyof T)                         │ keyof T                      │
│ Indexed          │ (indexed T K)                     │ T[K]                         │
│ Conditional      │ (if-extends T U X Y)              │ T extends U ? X : Y          │
│ Mapped           │ (mapped K Keys V)                 │ { [K in Keys]: V }           │
│ Tuple            │ (tuple A B)                       │ [A, B]                       │
│ Array            │ (array T)                         │ T[]                          │
│ Readonly         │ (readonly T)                      │ readonly T                   │
│ Typeof           │ (typeof x)                        │ typeof x                     │
│ Infer            │ (infer T)                         │ infer T                      │
│ Utility          │ (Partial T)                       │ Partial<T>                   │
│ Passthrough      │ (deftype N "complex<T>")          │ type N = complex<T>          │
├──────────────────┼───────────────────────────────────┼──────────────────────────────┤
│ OPERATORS        │                                   │                              │
│ Nullish Coal     │ (?? a b)                          │ a ?? b                       │
│ Opt Chain        │ obj?.prop                         │ obj?.prop                    │
│ ??= &&= ||=      │ (??= x 10)                        │ x ??= 10                     │
│ BigInt           │ 123n                              │ 123n                         │
├──────────────────┼───────────────────────────────────┼──────────────────────────────┤
│ MODULES          │                                   │                              │
│ Import           │ (import [a] from "m")             │ import { a } from "m"        │
│ Dynamic Import   │ (import-dynamic "./m.js")         │ import("./m.js")             │
│ Export           │ (export x)                        │ export { x }                 │
│ Export Default   │ (export-default x)                │ export default x             │
├──────────────────┼───────────────────────────────────┼──────────────────────────────┤
│ ERROR HANDLING   │                                   │                              │
│ Try/Catch        │ (try ... (catch e ...) (finally)) │ try {...} catch(e) {} fin... │
│ Throw            │ (throw (new Error "msg"))         │ throw new Error("msg")       │
└──────────────────┴───────────────────────────────────┴──────────────────────────────┘

// Create lazy sequence (thunk-based, memoized)
(lazy-seq (cons 1 (lazy-seq (cons 2 nil))))

// Seq protocol: first, rest, cons
(first [1 2 3])       // → 1
(rest [1 2 3])        // → (2 3)
(cons 0 [1 2 3])      // → (0 1 2 3)
(seq [1 2 3])         // → lazy seq or null if empty

// Delay/Force
(def d (delay (expensive-computation)))
(force d)             // Realize the delayed value
(realized d)          // Check if already forced

// Collection operations (all return lazy sequences)
(map inc [1 2 3])              // → (2 3 4)
(filter even? [1 2 3 4])      // → (2 4)
(reduce + 0 [1 2 3])          // → 6
(take 3 (range))              // → (0 1 2)
(drop 2 [1 2 3 4])            // → (3 4)
(concat [1 2] [3 4])          // → (1 2 3 4)
(flatten [[1 2] [3 [4]]])     // → (1 2 3 4)
(distinct [1 2 1 3 2])        // → (1 2 3)

// Infinite sequences
(range)                        // → 0, 1, 2, ... ∞
(range 5)                      // → 0, 1, 2, 3, 4
(range 1 10 2)                 // → 1, 3, 5, 7, 9
(repeat "x")                   // → "x", "x", "x", ... ∞
(cycle [1 2 3])                // → 1, 2, 3, 1, 2, 3, ... ∞
(iterate inc 0)                // → 0, 1, 2, 3, ... ∞

// Predicates
(some even? [1 3 4 5])        // → true
(every odd? [1 3 5])          // → true
(isEmpty [])                   // → true

// Transducers
(transduce (comp (map inc) (filter even?)) + 0 [1 2 3 4])

// Pure function declaration (compile-time enforcement)
(fx pure-add [a:number b:number] :number
  (+ a b))

// Effect types: Pure | Impure
// ValueKind tracking for receiver-type-aware purity
// See docs/features/21-effect-system/spec.md for details