1.1Minute 1: one-command install (recommended)

The installer supports macOS arm64, Linux x86_64, and Linux arm64. It detects the platform, downloads the V1.3.10 archive and matching .sha256, and installs only after verification. sudo is not required by default.

curl -fsSL https://hhylang.dev/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
hhy --version

1.2macOS: install from the Homebrew tap

Apple Silicon Macs can use the Formula maintained in this repository. The explicit Git URL lets the repository act as a tap before a separate homebrew-tap repository is created.

brew tap hh696-wq/hhy https://github.com/hh696-wq/hhy-vm.git
brew install hhy
hhy --version

1.3Option 2: download a Release

If you are not modifying the HHY Runtime, an official V1.3.10 archive is the fastest path. Choose darwin-arm64, linux-x86_64, or linux-arm64 for your OS and CPU. Archives include the executable, official sample and database extensions, required non-system runtime libraries, docs, licenses, and build metadata.

Open HHY GitHub Releases ↗
Download the latest stable archive and its matching .sha256 file or SHA256SUMS.
https://github.com/hh696-wq/hhy-vm/releases

tar -xzf hhy-1.3.10-PLATFORM-ARCH.tar.gz
cd hhy-1.3.10-PLATFORM-ARCH
./bin/hhy --version
./bin/hhy run examples/07-language-basics.hhy

1.4Verify the download and add it to PATH

Before running a download, verify it with the matching .sha256 file or SHA256SUMS. macOS includes shasum; Linux commonly provides sha256sum.

# macOS
shasum -a 256 -c hhy-1.3.10-darwin-arm64.tar.gz.sha256

# Linux
sha256sum -c hhy-1.3.10-linux-x86_64.tar.gz.sha256

# Add to PATH for this terminal (use the real absolute path)
export PATH="/absolute/path/hhy-1.3.10-PLATFORM-ARCH/bin:$PATH"
hhy --version

For permanent access, put the export PATH line in your shell profile. You may also keep invoking ./bin/hhy from the extracted directory without a system-wide install.

1.5Option 3: build from source

Build from source when developing the Runtime, validating current source, or choosing a custom installation prefix. HHY V1.3.10 supports macOS arm64, Linux arm64, and Linux x86_64 and requires a C11 compiler, make, libcurl, PCRE2, and BDWGC. The database extension additionally needs the corresponding PostgreSQL libpq or MySQL client development library.

brew install curl pcre2 bdw-gc
git clone https://github.com/hh696-wq/hhy-vm.git
cd hhy-vm
make
make test
./build/hhy --version

1.6Install the source build

make install PREFIX="$(brew --prefix)"
hhy --version

PREFIX may be a custom absolute path. Once PREFIX/bin is on PATH, execute any .hhy file with hhy run.

1.7Your first script

let language = "HHY"

["Flow", "Pipe", "System"]
    |> map { word -> "{language}: {word}" }
    |> print

hhy check hello.hhy
hhy run hello.hhy

let creates a binding; the List literal stores three Strings; |> injects the left value into the next call; the map closure creates one new String per item; print consumes the result. check validates lexical syntax, scope, modules, and known standard-library calls without effects.

1.8Running scripts and the development workflow

HHY source files use the .hhy suffix. View complete command help:

hhy --help

2.1What dynamic typing means

HHY declarations omit types; each value carries its logical type at runtime. Dynamic does not mean coercive: conditions require Bool, String never automatically becomes Number, Bool, or Path, and invalid arity or operations raise structured errors. Use type(value) to inspect a type and is_type(value, name) to test it.

let nothing = null
let enabled = true
let count = 42
let ratio = 0.75
let title = "HHY"
let pattern = /ERROR|WARN/i
let names = ["Ada", "Linus"]
let user = { name: "Ada", active: true }
let indexes = 0..3
let size_limit = 10mib
let timeout_limit = 5s
let completion = 80%

print(type(user))
print(is_type(title, "String"))

2.2Scalar and unit types

Precise String, number, unit, and Path edge cases belong in Reference. For ordinary scripts, remember that HHY never implicitly converts among String, Number, Bool, and Path.

Open the type and syntax reference →
Look up exact UTF-8, overflow, operator, and literal behavior.
/en/learn/syntax-reference

2.3List, Map, and Range

List indices start at zero and out-of-range access raises IndexError. Map keys are Strings and preserve insertion order; map.key equals map["key"]. A missing key normally returns null, while require distinguishes a missing key from a present key whose value is null. Range a..b includes a and excludes b without allocating a List.

let original = ["Flow", "System"]
let extended = append(original, "Pipe")
let shortened = remove_at(extended, 1)

let config = { retries: 3, label: null }
let updated = put(config, "timeout", 5s)
let selected = pick(updated, ["retries", "timeout"])

print(original)
print(shortened)
print(get(config, "missing"))
print(require(config, "label"))
print(selected)

Lists and Maps are not mutated in place. append, remove_at, put, remove_key, and pick return new collections, leaving original and config unchanged. Lists and Maps support deep equality; Functions, Streams, and system resources do not support value equality.

2.4Result, Stream, and system objects

System objects are not Maps. Map or pick ordinary fields before JSON encoding. Flow explains Stream laziness and consumption in detail.

2.5Bindings, scope, and immutability

let service = "api"
let mut retries = 0
retries = retries + 1

let creates a binding that cannot be reassigned; use let mut when reassignment is required. List and Map update functions return new collections rather than mutating originals. Names follow block lexical scope and must be declared before use.

2.6Conditions, loops, and functions

fn classify(score) {
    if score >= 90 { return "excellent" }
    else if score >= 60 { return "pass" }
    else { return "retry" }
}

let mut total = 0
for score in [98, 72, 55] {
    if score < 60 { continue }
    total = total + score
}

let mut attempts = 0
while attempts < 3 {
    attempts = attempts + 1
}

print(classify(98))
print(total)

HHY supports if / else if / else, for item in iterable, while, break, and continue. for iterates Lists, Map entries, Ranges, or Streams; iterating a Stream consumes it. Functions use positional arguments checked at call time and return null without an explicit return.

fn summarize(items) {
    let mut total = 0

    for item in items {
        if item.enabled {
            total = total + item.score
        }
    }

    return total
}

let users = [
    { name: "Ada", enabled: true, score: 98 },
    { name: "Linus", enabled: false, score: 86 }
]

summarize(users) |> print

A closure is { item -> expression }; a multi-statement closure must name its parameter and use return. A one-argument closure in an unambiguous Flow context may use { it * 2 }. V1.3.10 has no overloading, generics, or default arguments.

3.1How Pipe passes values

Pipe is a composition rule for ordinary calls: x |> f means f(x), x |> f(a) means f(x, a), and x |> obj.f(a) means obj.f(x, a). It does not turn scalars into Streams, flatten nested Streams, access it fields, ignore errors, stringify values, or invoke a shell.

[1, 2, 3, 4, 5]
    |> stream
    |> map { number -> number * 2 }
    |> where { number -> number > 5 }
    |> take(2)
    |> print

3.2Stream lifecycle

A Stream is a lazy, pull-based, single-consumption sequence. Building a pipeline only composes operators; upstream produces items when a terminal starts pulling. Its lifecycle is open → next* → close, and normal completion, early take, errors, and cancellation all close resources upstream.

3.3Item, filter, and observation operators

[5, 2, 5, 1, 3]
    |> stream
    |> skip(1)
    |> take(4)
    |> inspect { number -> print("seen {number}") }
    |> where { number -> number >= 3 }
    |> map { number -> number * 10 }
    |> distinct
    |> collect
    |> print

map(Stream<T>, Function(T -> U)) -> Stream<U>

where(Stream<T>, Function(T -> Bool)) -> Stream<T>

take(Stream<T>, Int) -> Stream<T>

skip(Stream<T>, Int) -> Stream<T>

inspect(Stream<T>, Function(T -> Value)) -> Stream<T>

distinct(Stream<Hashable>) -> Stream<Hashable>

3.4map versus flat_map

map sends exactly the closure result downstream. Returning a Stream therefore creates Stream<Stream<T>>. flat_map requires a Stream result and concatenates each child stream into one Stream.

let batches = [[1, 2], [3, 4]]

batches
    |> stream
    |> flat_map { batch -> batch |> stream }
    |> print

3.5What barriers and terminals actually do

Item operators retain only the current item. A barrier must inspect or retain substantial input before producing a correct result: sort_by stores all input before sorting, group_by stores every group's values, collect builds a List, and terminals such as reduce/count/sum read to completion before returning a scalar. All obey memory, collection-size, and runtime limits.

let ordered = [5, 1, 3, 2, 4]
    |> stream
    |> sort_by({ order: "asc" }) { number -> number }
    |> collect

let grouped = [
    { team: "core", name: "Ada" },
    { team: "web", name: "Linus" },
    { team: "core", name: "Grace" }
]
    |> stream
    |> group_by { person -> person.team }
    |> collect

print(ordered)
print(grouped)

sort_by(Stream<T>, Map, Function(T -> Comparable)) -> Stream<T>

group_by(Stream<T>, Function(T -> Hashable)) -> Stream<Group<T>>

collect(Stream<T>) -> List<T>

reduce(Stream<T>, U, Function(State<T,U> -> U)) -> U

count(Stream<T>) -> Int

sum(Stream<Number>) -> Number

min(Stream<Number>) -> Number | Null

max(Stream<Number>) -> Number | Null

first(Stream<T>) -> T | Null

last(Stream<T>) -> T | Null

any(Stream<T>, Function(T -> Bool)) -> Bool

all(Stream<T>, Function(T -> Bool)) -> Bool

3.6Effects, errors, and parallelism

Only a terminal or Action consumes a Pipeline. print, for_each, save_*, run, and send perform output, filesystem, process, or network work. Ordinary Errors terminate the Pipeline; use attempt for per-item Results and on_error to replace a failed upstream Stream.

parallel(n) uses isolated workers and preserves output order. Parallel and Watch covers concurrency limits, Sendable values, and cancellation.

4.1Path is not String

Every filesystem API requires Path. path(text) normalizes lexically: it collapses repeated separators and ., and resolves removable .. segments without accessing the filesystem or resolving symlinks. A relative Path is always based on the process startup directory, not the importing file.

let source = path("./src/../src/main.c")
let target = path_join(source.parent, "runtime.c")

print(source)
print(source.name)
print(source.extension)
print(source.parent)
print(target)

name, extension, and parent are read-only Path fields—not path_name(), path_extension(), or path_parent() functions. extension includes the leading dot and is empty when absent; path_join(base, child) returns a new combined Path.

4.2files: traversal, globs, and metadata

path("./logs")
    |> files("**/*.log")
    |> where { file -> file.size > 1mib }
    |> flat_map { file -> read_lines(file.path) }
    |> where { line -> contains(line, "ERROR") }
    |> save_lines(path("errors.txt"))

files(root, pattern, options?) returns a lazy Stream<File | Directory> and excludes the traversal root itself. Patterns support *, ?, and **. Directory symlinks are not followed by default; { follow_symlinks: true } opts in with cycle detection.

File and Directory are system objects, not Maps. Map required fields into an ordinary Map before JSON encoding.

4.3Reading text and binary data

read_text(Path) -> String

read_lines(Path) -> Stream<String>

read_bytes(Path) -> BytesBuffer

4.4Writing, appending, and atomic saves

let input = path("notes.txt")
let backup = path("backup/notes.txt")

write_text(input, "first line
", { overwrite: true })
append_text(input, "second line
")
copy(input, backup, { overwrite: false, create_parents: true })

read_lines(backup)
    |> map { line -> upper(line) }
    |> save_lines(path("backup/upper.txt"), { create_parents: true })

write_text(Path, String, Map?) -> Path

append_text(Path, String) -> Path

write_bytes(Path, BytesBuffer, Map?) -> Path

save_text(String | Stream<String>, Path, Map?) -> Path

save_lines(Stream<String>, Path, Map?) -> Path

write_text, write_bytes, save_text, and save_lines accept overwrite (default true) and create_parents (default false). They commit through a same-directory temporary file plus rename; overwrite: false uses atomic no-replace to prevent check-then-write races.

4.5Copy, move, remove, and dry-run

copy(Path, Path, Map?) -> Path

move(Path, Path, Map?) -> Path

remove(Path) -> Path

hhy run --dry-run backup.hhy
hhy run backup.hhy

Review the dry-run plan before executing a script that copies, moves, or removes files.

4.6Look up the complete API

Paths and files API Reference →
Look up every signature, parameter form, and stable function anchor.
/en/learn/standard-library#fn-path

5.1String and UTF-8

String is an immutable UTF-8 byte sequence. length counts Unicode code points, byte_length counts encoded bytes, and indexing returns a one-code-point String. Text functions return new values and never mutate the original.

let line = "  ERROR: timeout  "

line
    |> trim
    |> replace("ERROR", "WARN")
    |> lower
    |> print

trim(String) -> String

split(String, String) -> List<String>

join(List<String>, String) -> String

replace(String, String, String) -> String

contains(String | List, Value) -> Bool

starts_with(String, String) -> Bool

ends_with(String, String) -> Bool

lower(String) -> String

upper(String) -> String

5.2Regex

A Regex literal is /pattern/flags with i (case-insensitive), m (multiline), s (dot matches newline), and u. regex_match returns Bool; regex_captures returns the full match, byte positions, numbered groups, and named captures, or null when unmatched.

5.3JSON type mapping and errors

read_text(path("users.json"))
    |> parse_json
    |> get("users")
    |> stream
    |> where { user -> user.active == true }
    |> collect
    |> encode_json({ pretty: true })
    |> save_text(path("active-users.json"))

parse_json reports line and column on failure. encode_json accepts { pretty: true } for readable output. Function, Stream, and system objects require mapping to ordinary fields first.

5.4CSV is a record stream

parse_csv accepts a complete String or Stream<String> and returns Stream<Map>; encode_csv accepts Stream<Map> and returns Stream<String> records without terminators. Neither requires a whole-file buffer.

read_lines(path("employees.csv"))
    |> parse_csv({ header: true })
    |> where { row -> row.active == "true" }
    |> encode_csv({ header: true })
    |> save_lines(path("active-employees.csv"))

header controls field names; delimiter and quote must be single characters. CSV performs no schema inference, so numbers and Bools require explicit conversion. encode_csv omits terminators and composes with save_lines.

5.5Look up the complete API

Text and structured data API Reference →
Look up complete signatures for text, Regex, JSON, and CSV functions.
/en/learn/standard-library#fn-contains

6.1The safety boundary between run and shell

run(["git", "log", "--oneline"], { timeout: 5s })
    |> stdout_lines
    |> take(10)
    |> print

run(argv, options?) passes List<String> directly to the OS without a shell, so spaces, globs, $, redirects, and pipes are not reinterpreted. Use shell(command, options?) only when shell syntax is intentional; the Checker emits a safety hint.

6.2CommandResult

run and shell wait by default and return CommandResult. A nonzero child exit code is not automatically an HHY Error; inspect exit_code for business success.

A nonzero exit_code does not automatically become an HHY Error; interpret it according to the command. stdout_lines(result) exposes captured output as a line Stream.

6.3Process snapshots and fields

processes() returns a current Stream<Process> snapshot. Process is not a Map and exposes read-only pid, name, cpu, memory, status, and command fields. Explicitly map ordinary fields before JSON encoding.

6.4args, env, system, and stdin

if length(args) != 1 {
    print_error("usage: script.hhy <input>")
    exit(3)
}

let input = path(args[0])

6.5Look up the complete API

Processes and system API Reference →
Look up complete signatures for run, shell, processes, stdin_lines, and every.
/en/learn/standard-library#fn-run

7.1Request → Policy → Send → Response

http.get("https://example.com/users")
    |> timeout(5s)
    |> retry({ count: 3, backoff: 200ms })
    |> send
    |> response_body
    |> parse_json
    |> print

http.get/post/put/delete(url, options?) only build immutable HttpRequests without network access. timeout(request, duration) and retry(request, options) return new policy-adjusted Requests; send(request) performs the network effect and returns HttpResponse. Dry-run can therefore inspect the full plan without execution.

7.2Request options and safe defaults

TLS verification is enabled by default. Sensitive Authorization and Cookie headers are redacted in plans, logs, and Errors. Response bodies obey max_http_body.

7.3Timeout, retries, and idempotency

retry({ count, backoff }) defaults to connection errors, timeouts, 429, and selected 5xx statuses. GET, PUT, and DELETE may retry by policy; POST does not retry automatically to avoid duplicate creation or charges. Timeout and Ctrl+C cancel libcurl work and release response resources.

7.4HttpResponse and response bodies

send returns an in-memory HttpResponse. Use response_body for UTF-8 text and response_bytes for binary data; send_to(request, path) writes directly from curl into a sibling temporary file and atomically publishes it, returning only path and size.

http.get("https://api.example.com/status")
    |> timeout(3s)
    |> send
    |> response_body
    |> parse_json
    |> print

7.5Look up the complete API

HTTP API Reference →
Look up request builders, timeout, retry, send, and response readers.
/en/learn/standard-library#fn-http-get

8.1parallel is a bounded concurrent map

let urls = [
    "https://example.com",
    "https://example.org"
]

urls
    |> parallel(2) { url ->
    http.get(url)
        |> timeout(5s)
        |> send
}
    |> print

If a closure returns Stream, apply flat_map after parallel. Dry-run creates no workers but still checks closure Effects in order.

8.2Sendable values and isolation

Workers receive frozen snapshots of input and captured values, never shared mutable objects. Null, Bool, numbers, String, units, Path, and ordinary Lists/Maps/system snapshots whose fields are sendable can be copied.

8.3watch and FileEvent

watch(path("./src"))
    |> where { event -> event.kind == "write" }
    |> debounce(300ms)
    |> for_each { event ->
    print(event.path)
}

watch(path, { recursive? }) returns an infinite Stream<FileEvent>. FileEvent exposes read-only kind, path, old_path, and timestamp; kind is created, modified, removed, or renamed, and old_path exists only for renamed.

watch is an infinite Stream. End it with Ctrl+C, timeout, or cancel. Recursive watch obeys max_open_files, and filesystems may merge rapid duplicate events.

8.4debounce and every

debounce(window) is leading-edge: the first scalar or kind + path FileEvent emits immediately; duplicates inside the window are coalesced and reset the window. Different event keys do not block each other.

every(duration) returns an infinite tick Stream. If downstream is busy, backpressure prevents overlapping the same tick. Apply take or a business window before collect/sort/group.

8.5Cancellation and cleanup

Ctrl+C, timeout, cancel(), and unhandled errors trigger one root CancellationToken. Watchers, sleep, HTTP, child processes, and workers poll it; cancellation closes queues and handles, terminates children, and propagates Stream close upstream.

9.1Import forms and path resolution

import { add } from "./math.hhy"

add(20, 22) |> print

Relative paths resolve from the current source file. Standard modules use bare names; local files explicitly use ./, ../, or an absolute Path.

9.2Exports, scope, and execution

export let version = "1.0"

export fn normalize_name(name) {
    return name |> trim |> lower
}

fn internal_helper() {
    return null
}

Only exported names are visible to importers. A module owns its top-level scope, executes once on first import, and is then cached. Import cycles raise CheckError before execution. V1.3.10 supports standard and local modules plus process-extension modules installed from local packages.

9.3Error fields and categories

Every failure uses Error rather than null or printed text. Error exposes kind, code, message, source, stage, cause, stack, and context. Sensitive headers, credentials, and full file contents are excluded from context by default.

Built-in categories include SyntaxError, CheckError, TypeError, ValueError, IndexError, KeyError, EncodingError, IoError, ProcessError, HttpError, HttpStatusError, TimeoutError, CancelledError, ResourceLimitError, and PlanError.

9.4try/catch and rethrowing

try {
    read_text(path("config.json"))
        |> parse_json
        |> print
} catch err {
    print_error(err)
    exit(1)
}

catch receives the first Error propagated from try. Execution continues after a normally completed catch; use throw(err) to preserve the error chain when it cannot be handled. An unhandled Error exits nonzero.

9.5Flow errors and per-item Result

path("./configs")
    |> files("**/*.json")
    |> map { file -> attempt { read_text(file.path) } }
    |> where { result -> result.ok }
    |> map { result -> result.value }
    |> print

An unhandled Error in a Stream terminates the Pipeline. attempt converts one operation to Result for batches that explicitly retain successes and failures. on_error replaces an entirely failed upstream Stream and never silently skips an item.

9.6Resource cleanup guarantees

Error, return, exit, timeout, Ctrl+C, and cancel share one unwind path. Stream close is idempotent; failed atomic saves delete temporary files and preserve the old file; child processes, HTTP responses, watchers, and workers respond to cancellation.

10.100 · Hello HHY and Flow

The smallest runnable example: turn a List into a Stream, map and filter values, then print the result. Corresponds to examples/00-hello.hhy.

let language = "HHY"

["Flow", "Pipe", "System"]
    |> map { word -> "{language}: {word}" }
    |> print

HHY: Flow
HHY: Pipe
HHY: System

✓ exit 0 · Flow pipeline completed

10.2Extract log alerts concurrently

Recursively scan large log files with four workers, extract ERROR/WARN lines, and retain each source path. Useful for incident response and scheduled log jobs.

if length(args) != 2 {
    print_error("usage: hhy run log-errors.hhy <log-dir> <output-file>")
    exit(3)
}

let log_dir = path(args[0])
let output_file = path(args[1])

log_dir
    |> files("**/*.log")
    |> where { file -> file.size > 1mib }
    |> parallel(4) { file ->
    read_lines(file.path)
        |> where { line -> regex_match(line, /ERROR|WARN/) }
        |> map { line -> "{file.path}: {line}" }
        |> collect
}
    |> flat_map { lines -> lines |> stream }
    |> save_lines(output_file)
    |> on_error { err ->
    print_error(err)
    throw(err)
}

hhy run log-errors.hhy ./logs ./output/errors.txt

logs/api.log: 2026-08-25T09:18:42Z ERROR database timeout after 3000ms
logs/worker.log: 2026-08-25T09:18:44Z WARN retrying job #1842
logs/api.log: 2026-08-25T09:18:47Z ERROR upstream returned 502

✓ exit 0 · 3 alerts written to output/errors.txt

10.3Sync active users from an API

Fetch users with timeout and retry, parse JSON, select fields, and atomically save only active users. Corresponds to examples/02-active-users.hhy.

if length(args) != 2 {
    print_error("usage: hhy run active-users.hhy <url> <output-file>")
    exit(3)
}

http.get(args[0])
    |> timeout(5s)
    |> retry({ count: 3, backoff: 200ms })
    |> send
    |> response_body
    |> parse_json
    |> get("users")
    |> stream
    |> where { user -> user.active == true }
    |> map { user ->
    { id: user.id, name: user.name, email: user.email }
}
    |> collect
    |> encode_json({ pretty: true })
    |> save_text(path(args[1]))
    |> on_error { err ->
    print_error(err)
    throw(err)
}

hhy run active-users.hhy https://api.example.com/users active-users.json

[
  { "id": 101, "name": "Ada", "email": "ada@example.com" },
  { "id": 108, "name": "Linus", "email": "linus@example.com" }
]

✓ exit 0 · 2 active users written to active-users.json

10.4Monitor process CPU and memory

Sample processes every five seconds, keep CPU-heavy or memory-heavy entries, and print the top ten by memory. Corresponds to examples/03-process-monitor.hhy.

every(5s)
    |> for_each { tick ->
    processes
        |> where { process ->
        process.cpu > 70% or process.memory > 1gib
    }
        |> sort_by({ order: "desc" }) { process -> process.memory }
        |> take(10)
        |> map { process ->
        {
            pid: process.pid,
            name: process.name,
            cpu: process.cpu,
            memory: process.memory
        }
    }
        |> print
}

[{ pid: 8421, name: "node", cpu: 82.4%, memory: 1.42 GiB },
 { pid: 9107, name: "hhy",  cpu: 74.1%, memory: 86.3 MiB }]

next sample in 5s… · Ctrl+C exits safely

10.5Check service health in batches

Probe multiple services concurrently with consistent timeouts and retries. A failed endpoint is recorded without terminating the whole batch.

let services = [
    { name: "users", url: "https://api.example.com/users/health" },
    { name: "orders", url: "https://api.example.com/orders/health" },
    { name: "billing", url: "https://api.example.com/billing/health" }
]

services
    |> stream
    |> parallel(3) { service ->
    let response = attempt {
        http.get(service.url)
            |> timeout(3s)
            |> retry({ count: 2, backoff: 100ms })
            |> send
            |> response_body
            |> parse_json
    }

    let mut status = "unreachable"
    let mut error_message = null

    if response.ok {
        status = response.value.status
    } else {
        error_message = response.error.message
    }

    return {
        name: service.name,
        ok: response.ok,
        status: status,
        error: error_message
    }
}
    |> collect
    |> encode_json({ pretty: true })
    |> print

[
  { "name": "users",   "ok": true,  "status": "healthy", "error": null },
  { "name": "orders",  "ok": true,  "status": "healthy", "error": null },
  { "name": "billing", "ok": false, "status": "unreachable", "error": "request timed out" }
]

✓ exit 0 · all 3 checks completed despite one endpoint failure

10.6Business 01 · Release quality gate

Run tests, lint, and production builds in parallel, save a machine-readable report, and block a release with a stable exit code when any check fails.

let checks = [
    { name: "unit-tests", command: ["make", "test"] },
    { name: "lint", command: ["npm", "run", "lint"] },
    { name: "production-build", command: ["npm", "run", "build"] }
]

let report = checks
    |> stream
    |> parallel(3) { check ->
    let result = run(check.command, { timeout: 10min, max_output: 8mib })
    return {
        name: check.name,
        passed: result.exit_code == 0,
        exit_code: result.exit_code,
        output: result.stdout
    }
}
    |> collect

report |> encode_json({ pretty: true }) |> save_text(path("release-gate.json"))

if report |> any { check -> check.passed == false } {
    print_error("release blocked: one or more checks failed")
    exit(1)
}

print("release gate passed")

unit-tests       PASS  4.28s
lint             PASS  1.14s
production-build PASS  6.72s
release-gate.json written

✓ exit 0 · release gate passed

10.7Business 02 · Source secret audit

Scan configuration and source files concurrently for suspected API keys, passwords, and private keys, then produce a security review report.

if length(args) != 2 {
    print_error("usage: hhy run secret-audit.hhy <source-dir> <report-file>")
    exit(3)
}

path(args[0])
    |> files("**/*")
    |> where { file ->
    file.extension == ".env" or
    file.extension == ".yml" or
    file.extension == ".json" or
    file.extension == ".ts"
}
    |> parallel(4) { file ->
    read_lines(file.path)
        |> where { line ->
        regex_match(line, /API_KEY|SECRET|PASSWORD|BEGIN PRIVATE KEY/)
    }
        |> map { line -> "{file.path}: {line}" }
        |> collect
}
    |> flat_map { matches -> matches |> stream }
    |> save_lines(path(args[1]))

services/billing/.env: PAYMENT_API_KEY=***
services/auth/config.yml: PASSWORD: ***

✓ exit 0 · 2 suspected secrets require review

10.8Business 03 · Order and payment reconciliation

Merge order and payment CSV files into one flow, group records by order_id, and report missing records or mismatched amounts.

if length(args) != 3 {
    print_error("usage: hhy run reconcile.hhy <orders.csv> <payments.csv> <report.json>")
    exit(3)
}

[path(args[0]), path(args[1])]
    |> stream
    |> flat_map { input ->
    read_lines(input) |> parse_csv({ header: true })
}
    |> group_by { record -> record.order_id }
    |> where { group ->
    (group.values |> count) != 2 or
    (group.values |> map { record -> record.amount } |> distinct |> count) != 1
}
    |> map { group ->
    { order_id: group.key, records: group.values, issue: "missing_or_amount_mismatch" }
}
    |> collect
    |> encode_json({ pretty: true })
    |> save_text(path(args[2]))

orders: 12,480 · payments: 12,472
matched: 12,461
exceptions: 19 → exceptions.json

✓ exit 0 · reconciliation report written atomically

10.9Business 04 · Multi-tenant usage snapshot

Fetch tenant usage with bounded concurrency, consistent retries, and failure isolation. Useful for billing, capacity analysis, and customer success reports.

let tenants = [
    { id: "acme", url: "https://api.example.com/acme/usage" },
    { id: "nova", url: "https://api.example.com/nova/usage" },
    { id: "orbit", url: "https://api.example.com/orbit/usage" }
]

tenants
    |> stream
    |> parallel(3) { tenant ->
    let result = attempt {
        http.get(tenant.url)
            |> timeout(5s)
            |> retry({ count: 3, backoff: 200ms })
            |> send
            |> response_body
            |> parse_json
    }

    if result.ok {
        return { tenant: tenant.id, ok: true, usage: result.value, error: null }
    }

    return { tenant: tenant.id, ok: false, usage: null, error: result.error.message }
}
    |> collect
    |> encode_json({ pretty: true })
    |> save_text(path("tenant-usage-snapshot.json"))

acme  ✓ requests=184203 storage_gb=82.4
nova  ✓ requests=99102  storage_gb=41.8
orbit ✗ request timed out

✓ exit 0 · snapshot contains both data and failure reasons

10.10Business 05 · Oversized asset governance

Find large image and video assets, sort them by size, and produce a JSON inventory for compression or storage migration work.

if length(args) != 2 {
    print_error("usage: hhy run asset-audit.hhy <asset-dir> <report.json>")
    exit(3)
}

path(args[0])
    |> files("**/*")
    |> where { file ->
    file.is_file and
    (file.extension == ".png" or file.extension == ".jpg" or file.extension == ".mp4")
}
    |> where { file -> file.size > 5mib }
    |> sort_by({ order: "desc" }) { file -> file.size }
    |> map { file ->
    { path: file.path, bytes: file.size, extension: file.extension }
}
    |> collect
    |> encode_json({ pretty: true })
    |> save_text(path(args[1]))

scanned 1,842 assets
large assets: 27
largest: public/video/launch.mp4 · 184.2 MiB

✓ exit 0 · asset-report.json generated

10.11Watch sources and rebuild

Watch C sources, debounce rapid saves, and run make. Build failures are reported while the watcher stays alive.

if length(args) != 1 {
    print_error("usage: hhy run watch-build.hhy <source-dir>")
    exit(3)
}

let source_dir = path(args[0])

watch(source_dir, { recursive: true })
    |> where { event ->
    event.kind != "removed" and
    (event.path.extension == ".c" or event.path.extension == ".h")
}
    |> debounce(300ms)
    |> for_each { event ->
    print("changed: {event.path}")

    let result = run(["make"], { timeout: 2min, cwd: system.cwd })

    if result.exit_code != 0 {
        print_error(result.stderr)
    } else {
        print(result.stdout)
    }
}

hhy run watch-build.hhy ./src

watching ./src recursively…
changed: src/runtime/flow.c
cc -std=c11 -O2 -c src/runtime/flow.c
cc build/*.o -lcurl -lpcre2-8 -lgc -o build/hhy
Build complete: build/hhy

✓ watcher remains active · waiting for the next change

10.12Build a department report from CSV

Read employee CSV records, keep active employees, aggregate headcount and salary by department, and atomically save formatted JSON.

if length(args) != 2 {
    print_error("usage: hhy run csv-report.hhy <input.csv> <output.json>")
    exit(3)
}

read_lines(path(args[0]))
    |> parse_csv({ header: true })
    |> where { employee -> employee.active == "true" }
    |> group_by { employee -> employee.department }
    |> map { group ->
    {
        department: group.key,
        employees: group.values |> count,
        total_salary: group.values
            |> map { employee -> employee.salary |> to_float }
            |> sum
    }
}
    |> collect
    |> encode_json({ pretty: true })
    |> save_text(path(args[1]))

hhy run csv-report.hhy employees.csv department-report.json

[
  { "department": "Engineering", "employees": 12, "total_salary": 2160000 },
  { "department": "Product", "employees": 5, "total_salary": 810000 }
]

✓ exit 0 · department-report.json written atomically

10.13Back up large files with dry-run

Find files over 100 MiB and copy them into a backup directory. Inspect the plan with dry-run before performing real writes.

if length(args) != 2 {
    print_error("usage: hhy run backup-large.hhy <source-dir> <backup-dir>")
    exit(3)
}

let source_dir = path(args[0])
let backup_dir = path(args[1])

source_dir
    |> files("**/*")
    |> where { file -> file.is_file and file.size > 100mib }
    |> for_each { file ->
    let target = path_join(backup_dir, file.name)
    print("copy {file.path} -> {target}")
    copy(file.path, target, { overwrite: false, create_parents: true })
}
    |> on_error { err ->
    print_error(err)
    throw(err)
}

hhy run --dry-run backup-large.hhy ./downloads ./backup
hhy run backup-large.hhy ./downloads ./backup

copy downloads/archive.tar -> backup/archive.tar
copy downloads/database.dump -> backup/database.dump
[dry-run] copy downloads/archive.tar → backup/archive.tar
[dry-run] copy downloads/database.dump → backup/database.dump

✓ exit 0 · plan generated without writing files

10.1407 · Language basics in one task

A small aggregation task combining variables, Lists, Maps, functions, conditions, loops, scopes, and error handling. Corresponds to examples/07-language-basics.hhy.

fn summarize(items) {
    let mut total = 0

    for item in items {
        if item.enabled {
            total = total + item.score
        }
    }

    return total
}

let users = [
    { name: "Ada", enabled: true, score: 98 },
    { name: "Linus", enabled: false, score: 86 }
]

summarize(users) |> print

{
  "count": 2,
  "total": 40,
  "average": 20
}

✓ exit 0 · summary generated

11.1More than a syntax demo

FlowGuard is a complete application run and self-tested with HHY v1.3.10. It accepts a project directory and JSON configuration, checks required files, scans files and possible credentials, runs quality commands and HTTP health checks concurrently, atomically writes a structured report, and uses a stable exit code to enforce the quality gate.

View the complete FlowGuard source on GitHub ↗
Includes the HHY entry point, six business modules, configurations, fixtures, HTTP server, and report assertions.
https://github.com/hh696-wq/hhy-vm/tree/main/practical-projects/flowguard

11.2Project layout

The entry script focuses on orchestration while lib contains each check. Config holds two scenarios, and fixtures provides repeatable project data. output and __pycache__ are ignored and never committed.

11.3Run the complete self-test

Run one command from the repository root. The test starts a temporary HTTP service bound only to 127.0.0.1:18991, checks the HHY modules, runs both scenarios, and uses Python assertions to validate the generated JSON reports.

cd hhy-vm
sh practical-projects/flowguard/self-test.sh

11.4Healthy and risky scenarios

11.5Configure your own project

{
  "project": { "name": "my-service" },
  "required_files": ["README.md", "LICENSE"],
  "limits": { "large_file": "4kib" },
  "commands": [
    { "name": "tests", "argv": ["npm", "test"] }
  ],
  "health_checks": [
    { "name": "api", "url": "http://127.0.0.1:8080/health" }
  ]
}

Commands are passed directly to run as argv arrays and are never assembled through shell. Each command is limited to 15 seconds and 1 MiB of output. The current example accepts 256b, 1kib, 4kib, or 1mib file thresholds.

hhy run \
  --limit max_runtime=2min \
  --limit max_memory=256mib \
  --limit max_processes=8 \
  practical-projects/flowguard/flowguard.hhy \
  /path/to/project \
  practical-projects/flowguard/config/my-project.json \
  report.json

11.6Why it represents HHY

FlowGuard brings filesystem, process, HTTP, and data processing into one reliable workflow. attempt turns an individual failure into a structured check without preventing other checks from completing; parallel provides bounded concurrency; and CI/CD can consume the final report directly. This is where HHY is most distinct from a large shell script.

Read the FlowGuard guide ↗
See configuration fields, manual commands, test design, and instructions for checking a real project.
https://github.com/hh696-wq/hhy-vm/blob/main/practical-projects/flowguard/README.md

12.1A complete synchronization pipeline

DataFlow ETL runs entirely on HHY v1.3.10 and is verified end to end. It reads customer CSV and an event JSON directory, normalizes names and email addresses, filters inactive and low-spend customers, calls a profile API concurrently, aggregates departments with group_by, and atomically writes JSON and CSV outputs.

View the complete DataFlow ETL source on GitHub ↗
Includes HHY modules, CSV/JSON fixtures, profile API, report assertions, and one-command self-test.
https://github.com/hh696-wq/hhy-vm/tree/main/practical-projects/dataflow-etl

12.2Real layout and data flow

customers.csv + events/*.json + HTTP profiles
                    ↓
            parse / trim / lower
                    ↓
          active + minimum spend filter
                    ↓
          parallel HTTP enrichment
                    ↓
          group_by department + sum
                    ↓
              report.json + customers.csv

12.3Actual self-test result

cd hhy-vm
sh practical-projects/dataflow-etl/self-test.sh

12.4Run your own synchronization

Copy config/test.json, replace the project name, API base, and minimum-spend threshold, then provide customers.csv and events/*.json. An individual HTTP failure becomes a structured error, sets report ok=false, and returns exit code 1.

hhy run practical-projects/dataflow-etl/etl.hhy \
  ./input \
  ./config.json \
  ./output/report.json \
  ./output/customers.csv

13.1Separate audit from remediation

Asset Governance consists of audit.hhy and cleanup.hhy. The auditor scans source, configuration, images, video, and build outputs for oversized, stale, badly named, duplicate-text, and possibly sensitive files. The cleaner accepts only allow-listed report actions and never assembles shell commands.

View the complete Asset Governance source on GitHub ↗
Includes auditor, cleaner, four HHY modules, risky fixtures, and dry-run plus applied-remediation assertions.
https://github.com/hh696-wq/hhy-vm/tree/main/practical-projects/asset-governance

13.2Project layout

13.3Actual self-test and dry-run

cd hhy-vm
sh practical-projects/asset-governance/self-test.sh

13.4Two-phase operation

Run the audit and inspect report.json first. audit returns 1 for a critical finding but still writes the complete report. After approving actions, run dry-run, inspect Runtime's effect plan, and only then apply remediation.

hhy run practical-projects/asset-governance/audit.hhy ./project ./config.json ./report.json
hhy run --dry-run practical-projects/asset-governance/cleanup.hhy ./project ./report.json
hhy run practical-projects/asset-governance/cleanup.hhy ./project ./report.json

14.1Real network research with HHY

This project uses HHY v1.3.10 with the official MediaWiki API. It searches for ten pages related to “香港電影公司”, fetches page IDs, canonical URLs, timestamps, and bounded introductions with parallel(3), retains entries that mention Hong Kong, film, and a company, sorts by title, and atomically writes CSV and JSON.

View the complete source on GitHub ↗
Includes the HHY crawler, configuration, modules, local MediaWiki fixture, CSV/JSON assertions, and bilingual guides.
https://github.com/hh696-wq/hhy-vm/tree/main/practical-projects/hong-kong-film-companies

14.2Project layout

14.3Actual Wikipedia result

On 2026-08-26, the actual run fetched all ten candidate details and retained seven company-related results: China Star Entertainment Group, Cathay Organisation, One Cool Film, Mandarin Films, Shaw Brothers, Film Workshop, and the Hong Kong film-company list.

./build/hhy run --limit max_runtime=2min --limit max_parallelism=8 \
  practical-projects/hong-kong-film-companies/crawl.hhy \
  practical-projects/hong-kong-film-companies/config/wikipedia.json \
  practical-projects/hong-kong-film-companies/output/wikipedia-report.json \
  practical-projects/hong-kong-film-companies/output/wikipedia-hong-kong-film-companies.csv

14.4Concurrency, limits, and repeatability

The default parallelism is three and each introduction is capped at 600 characters, bounding worker results. Requests use a ten-second timeout and two retries; attempt isolates each detail task. The Chinese keyword is percent-encoded in search_url to accommodate HHY 1.1.1's current non-ASCII query Map limitation.

sh practical-projects/hong-kong-film-companies/self-test.sh

Read the English guide ↗
See output fields, the real crawl command, configuration limits, and deterministic test design.
https://github.com/hh696-wq/hhy-vm/blob/main/practical-projects/hong-kong-film-companies/README.md

15.1One reliable collection flow

Built with HHY v1.3.10, this project collects two pages each from OpenAlex, Crossref, and GitHub. parallel(3) bounds concurrent HTTP downloads before heterogeneous JSON is normalized into one seven-column schema.

View the complete source on GitHub ↗
Includes the HHY entry point, pagination jobs, three adapters, incremental merge, configuration, and deterministic self-test.
https://github.com/hh696-wq/hhy-vm/tree/main/practical-projects/multi-api-data-collector

15.2Project layout

15.3Run and incremental result

./build/hhy run practical-projects/multi-api-data-collector/collector.hhy \
  practical-projects/multi-api-data-collector/config/public-apis.json \
  practical-projects/multi-api-data-collector/output/records.csv \
  practical-projects/multi-api-data-collector/output/report.json \
  practical-projects/multi-api-data-collector/output/failures.json

15.4Verification

sh practical-projects/multi-api-data-collector/self-test.sh

The test runs twice to verify pagination, concurrency, normalization, cross-page deduplication, stable sorting, the failure list, and incremental replacement.

16.1A quality gate that uses the safe spider end to end

SiteGraph Auditor builds on HHY v1.3.10 and the safe recursive my-crawler engine. Starting from seeds, it discovers pages by depth and writes an inventory, normalized graph, report, and failures. A stable exit status blocks sites with missing metadata or crawl failures.

View the complete SiteGraph Auditor source ↗
Includes three HHY modules, a four-level healthy site, a risky site, report assertions, and a negative SSRF test.
https://github.com/hh696-wq/hhy-vm/tree/main/practical-projects/sitegraph-auditor

16.2Healthy and risky scenarios

make
./practical-projects/sitegraph-auditor/self-test.sh

SiteGraph Auditor healthy
Pages 4 / 4 Edges 5
Duplicates 3 Rejected 1 Findings 0
SiteGraph Auditor risky
Pages 1 / 2 Edges 2
Duplicates 0 Rejected 1 Findings 3
SiteGraph Auditor self-test passed

The healthy site has four levels, relative URLs, dot segments, fragment duplicates, and an external reference. The risky site has missing description/canonical metadata, a 404, and an out-of-scope path. A final request proves safe mode rejects loopback.

16.3Outputs and boundary

17.1Source files and lexical rules

17.2Literals and native units

let nothing = null
let flags = [true, false]
let numbers = [42, -10, 0xff, 0b1010, 1.5, 1e6]
let name = "HHY"
let strings = ["hello", "Hello, {name}"]
let pattern = /ERROR|WARN/i
let list = [1, 2, 3]
let record = { name: "Tom", age: 20 }
let interval = 1..10
let units = [10mib, 5s, 80%]

Ranges include the start and exclude the end. Bytes support b/kb/mb/gb/kib/mib/gib; Duration supports ns/us/ms/s/min/h; % attached to a number creates Percent. Strings support interpolation and \, ", \n, \r, \t, \b, \f, and \0 escapes.

17.3Operator precedence (highest to lowest)

()  []  .
not  -  +
*  /  %
+  -
<  <=  >  >=
==  !=
and
or
??
|>
=

and, or, and ?? short-circuit; = may assign only to a let mut binding; |> is left-associative. Conditions require Bool—0, empty strings, and null are not implicitly false.

17.4Declarations, control flow, functions, and modules

let name = "HHY"
let mut count = 0
count = count + 1
let enabled = true
let items = ["Flow", "Pipe"]

if enabled { print("yes") } else { print("no") }
for item in items { print(item) }
while count < 3 { count = count + 1 }

fn add(a, b) { return a + b }
let doubled = [1, 2] |> stream |> map { number -> number * 2 } |> collect

try { read_text(path("config.json")) } catch err { print_error(err) }
let result = attempt { read_text(path("config.json")) }

import { add as sum_two } from "./math.hhy"
export fn public_api(value) { return value }

17.5Core value types

Null Bool Int Float String Regex BytesBuffer
List Map Range Function Error Result Stream
Bytes Duration Percent DateTime Path
File Directory FileEvent Process CommandResult
HttpRequest HttpResponse

18.1Reading the signatures

This page is sourced from the V1.3.10 Runtime Callable Contract Registry and contains all 96 core callables; dynamically registered callables are documented by their extensions. T/U are generic placeholders, ? marks an optional argument or nullable result, and Map? is an optional options Map. Every function supports ordinary calls; a pipe injects its left value as the first argument.

18.2Core values, collections, environment, and control (22)

print(Value...) -> Null

print_error(Value...) -> Null

exit(Int?) -> Never

length(String | List | Map) -> Int

byte_length(String | BytesBuffer) -> Int

type(Value) -> String

is_type(Value, String) -> Bool

to_int(Int | Float | String) -> Int

to_float(Int | Float | String) -> Float

get(List | Map | Record, Int | String) -> Value | Null

require(Map, String) -> Value

pick(Map, List<String>) -> Map

put(Map, String, Value) -> Map

remove_key(Map, String) -> Map

append(List<T>, T) -> List<T>

remove_at(List<T>, Int) -> List<T>

now() -> DateTime

datetime.parse(String, String, String) -> DateTime

require_env(String) -> String

sleep(Duration) -> Null

cancel() -> Never

throw(Error) -> Never

18.3Flow and Stream (25)

Transformations such as map, where, and take stay lazy; terminals such as collect, count, and reduce consume the Stream. sort_by and group_by materialize input within resource limits. parallel uses bounded isolated workers and preserves output order.

stream(List<T> | Map | Range) -> Stream<T>

range(Int, Int) -> Stream<Int>

map(Stream<T>, Function(T -> U)) -> Stream<U>

flat_map(Stream<T>, Function(T -> Stream<U>)) -> Stream<U>

where(Stream<T>, Function(T -> Bool)) -> Stream<T>

take(Stream<T>, Int) -> Stream<T>

skip(Stream<T>, Int) -> Stream<T>

inspect(Stream<T>, Function(T -> Value)) -> Stream<T>

distinct(Stream<Hashable>) -> Stream<Hashable>

sort_by(Stream<T>, Map, Function(T -> Comparable)) -> Stream<T>

group_by(Stream<T>, Function(T -> Hashable)) -> Stream<Group<T>>

debounce(Stream<T>, Duration) -> Stream<T>

on_error(Stream<T>, Function(Error -> Stream<T>)) -> Stream<T>

parallel(Stream<T>, Int, Function(T -> U)) -> Stream<U>

collect(Stream<T>) -> List<T>

count(Stream<T>) -> Int

first(Stream<T>) -> T | Null

last(Stream<T>) -> T | Null

min(Stream<Number>) -> Number | Null

max(Stream<Number>) -> Number | Null

sum(Stream<Number>) -> Number

reduce(Stream<T>, U, Function(State<T,U> -> U)) -> U

any(Stream<T>, Function(T -> Bool)) -> Bool

all(Stream<T>, Function(T -> Bool)) -> Bool

for_each(Stream<T>, Function(T -> Value)) -> Null

18.4Text, Regex, JSON, and CSV (18)

contains(String | List, Value) -> Bool

upper(String) -> String

lower(String) -> String

trim(String) -> String

trim_start(String) -> String

trim_end(String) -> String

starts_with(String, String) -> Bool

ends_with(String, String) -> Bool

replace(String, String, String) -> String

split(String, String) -> List<String>

join(List<String>, String) -> String

regex_match(String, Regex) -> Bool

regex_captures(String, Regex) -> Map | Null

url_resolve(String, String?) -> Map

parse_json(String) -> JsonValue

encode_json(JsonValue, Map?) -> String

parse_csv(String | Stream<String>, Map?) -> Stream<Map>

encode_csv(Stream<Map>, Map?) -> Stream<String>

18.5Paths, files, and watch (15)

read_* functions read data, write_* functions write directly, and save_* functions use a temporary file plus atomic replacement. Dry-run intercepts filesystem actions.

path(String) -> Path

path_join(Path, String | Path) -> Path

files(Path, String, Map?) -> Stream<File | Directory>

read_text(Path) -> String

read_lines(Path) -> Stream<String>

read_bytes(Path) -> BytesBuffer

write_text(Path, String, Map?) -> Path

append_text(Path, String) -> Path

write_bytes(Path, BytesBuffer, Map?) -> Path

save_text(String | Stream<String>, Path, Map?) -> Path

save_lines(Stream<String>, Path, Map?) -> Path

copy(Path, Path, Map?) -> Path

move(Path, Path, Map?) -> Path

remove(Path) -> Path

watch(Path, Map?) -> Stream<FileEvent>

18.6Processes, standard input, and timers (6)

run passes argv directly without a shell; only shell explicitly uses shell parsing. Process launches obey timeout, output, and process-count limits.

run(List<String>, Map?) -> CommandResult

shell(String, Map?) -> CommandResult

stdout_lines(CommandResult) -> Stream<String>

processes() -> Stream<Process>

stdin_lines() -> Stream<String>

every(Duration) -> Stream<Int>

18.7HTTP (10)

http.* only builds immutable request plans, timeout/retry transform a plan, and only send performs a network effect. response_body returns UTF-8 text; use response_bytes for binary data.

http.get(String, Map?) -> HttpRequest

http.post(String, Map?) -> HttpRequest

http.put(String, Map?) -> HttpRequest

http.delete(String, Map?) -> HttpRequest

timeout(HttpRequest, Duration) -> HttpRequest

retry(HttpRequest, Map) -> HttpRequest

send(HttpRequest) -> HttpResponse

send_to(HttpRequest, Path) -> HttpResponse

response_body(HttpResponse) -> String

response_bytes(HttpResponse) -> BytesBuffer

19.1Version and release identity

Use --version to confirm the binary version, project author, open-source license, and official contact details. Source builds use ./build/hhy; release archives or PATH installations can invoke hhy directly.

hhy 1.3.10
© 2026 HHY Language contributors
Author: houhuiyang
License: Apache License 2.0
https://hhylang.dev/
huiyang.hou@qq.com

19.2Complete command set

hhy script.hhy [args...]
hhy run script.hhy [args...]
hhy repl
hhy check script.hhy...
hhy fmt script.hhy...
hhy fmt --check script.hhy...
hhy ast script.hhy
hhy bytecode script.hhy
hhy bytecode --metrics script.hhy
hhy tokens script.hhy
hhy run --dry-run script.hhy
hhy run --limit max_runtime=30s --limit max_memory=256mib script.hhy
hhy profile script.hhy [args...]
hhy profile --cpu script.hhy
hhy profile --heap --format json --output profile.json script.hhy
hhy --version
hhy --help

hhy script.hhy is shorthand for hhy run script.hhy. Use -- after Runtime options when script arguments may begin with a dash.

19.3Bytecode cache admission evidence

v1.3.10 adds read-only --metrics output for measuring real compile+verify and execution-plan verification cost. Across five fixed workloads and 21 paired fresh-process samples, compile+verify medians were 0.004–0.012 ms, only 0.0078%–0.1341% of cold-run wall time, below the joint 1 ms and 20% thresholds.

{"bytecode_format_version":1,"compile_verify_ns":9000,"constants":21,"instructions":40,"schema_version":1,"source_bytes":167,"stream_kernel_version":1,"stream_kernels":1,"tool":"hhy bytecode --metrics","verify_prepare_ns":4000}

19.4CPU and Heap profiling

profile executes the script and collects CPU and managed-Heap data in the same run by default. Reports go to stderr, leaving script stdout unchanged, and the command preserves the script's exit code.

hhy profile examples/09-profile-algorithms.hhy -- fibonacci 20
hhy profile --cpu examples/09-profile-algorithms.hhy fibonacci 20
hhy profile --heap --format json --output profile.json examples/09-profile-algorithms.hhy fibonacci 20

HHY profile: examples/09-profile-algorithms.hhy

Summary
  Wall time        0.006 s
  CPU time         0.004 s
  CPU utilization  64.5%
  CPU samples      2
  Heap peak        755.9 KiB
  Heap after GC    4.0 KiB
  Allocated        523.9 KiB
  Allocations      11107

CPU hotspots
  CPU%    Samples      Calls  Function
  100.0%        2      21891  fibonacci  examples/09-profile-algorithms.hhy:5:1

Allocation hotspots
  Bytes          Objects  Function
  515.6 KiB        10966  fibonacci  examples/09-profile-algorithms.hhy:5:1

fibonacci 6765

19.5Interpreter performance evolution

v1.3.10 defaults to the Compiler/Verifier-validated Bytecode VM. Native Opcode dispatch, static slots, reusable call frames, and low-allocation closure fast paths reduce CPU cost; the AST Interpreter remains the permanent semantic oracle and explicit fallback.

19.6Runtime resource limits

The run command accepts repeatable --limit NAME=VALUE options. Sizes require b/kb/mb/gb/kib/mib/gib, durations require ns/us/ms/s/min/h, and counts have no unit.

hhy run --limit max_runtime=30s --limit max_memory=256mib script.hhy

19.7Stable exit codes

0  success
1  unhandled runtime error
2  syntax or static-check error
3  invalid CLI usage
4  file I/O, process, or network error
5  timeout or cancellation

Automation should branch on stable exit codes rather than error text.

20.1The current extension boundary

A package name is its top-level namespace: package_name may register only package_name.* and cannot replace hhy.*, std.*, core callables, or another package. Importing an uninstalled package raises ModuleNotFoundError.

20.2Available official extensions

Database Extension Guide
Install database 0.2.0 and perform MySQL/PostgreSQL queries, writes, and transactions.
/en/learn/database-extension

HTML Extension and Crawler Framework
Use html 0.2.0 with observable batch extraction, URL normalization, a safe frontier, deduplication, and SSRF protection.
/en/learn/html-crawler-framework

20.3Where to get extensions

# Build and install from source (html example)
git clone https://github.com/hh696-wq/hhy-vm.git
cd hhy-vm
make
make -C extensions/html
./build/hhy install ./extensions/html

# Inspect installed extensions
./build/hhy list

Open the official extension index ↗
One extension version may contain darwin-arm64, linux-x86_64, linux-arm64, and windows-x86_64 targets; the installer selects only its native target.
https://registry.hhylang.dev/index.json

Browse extension source on GitHub ↗
Source, hhy.toml manifests, tests, and build scripts for sample, html, and database.
https://github.com/hh696-wq/hhy-vm/tree/main/extensions

20.4Install, list, and remove

./build/hhy install ./path/to/extension
./build/hhy list
./build/hhy remove package-name

20.5Generic hhy.toml manifest

[package]
name = "package-name"
version = "0.1.0"
author = "Your Organization"
requires_hhy = ">=1.1,<2.0"

[extension]
kind = "process"
command = "bin/hhy-package"
protocol = "1"

[capabilities]
read = []
write = []
network = []
process = false

20.6How an extension loads

20.7What an extension author must implement

The extension process does not receive the complete host environment; Runtime passes only arguments explicitly supplied by the script. Errors should remain actionable without including passwords, tokens, complete connection addresses, or other sensitive information.

21.1What the database extension is

21.2Install the extension and its four callables

make -C extensions/database
./build/hhy install ./extensions/database
./build/hhy list

install validates hhy.toml, the HHY version range, the extension command, and SHA-256 integrity, then displays network capabilities before confirmation. After installation, import database starts the isolated extension process, completes the Protocol 1 handshake, and registers all four callables.

21.3Connection configuration and credential safety

cd extensions/database/examples/hhy_extension_test
cp config.example.json config.local.json
chmod 600 config.local.json

{
  "url": "mysql://root:CHANGE_ME@127.0.0.1:3306/hhy_extension_test",
  "database": "hhy_extension_test",
  "max_rows": 1000
}

21.4Project one: inspect the test database read-only

./build/hhy run \
  extensions/database/examples/hhy_extension_test/read.hhy \
  extensions/database/examples/hhy_extension_test/config.local.json

import database
import { load_database_config } from "./lib/config.hhy"

let config = load_database_config(args[0])
let result = database.query(
    config.url,
    "SELECT COUNT(*) AS table_count FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? AND TABLE_TYPE = 'BASE TABLE'",
    [config.database],
    1
)

print("Database", config.database)
print("Table count", result.rows[0].table_count)

The complete read.hhy in the repository also lists every table's name, storage engine, and estimated row count. SQL values go through the driver's prepared-statement parameter API and are never concatenated into the query text.

21.5Project two: controlled writes and transactions

./build/hhy run extensions/database/examples/hhy_extension_test/write-demo.hhy \
  extensions/database/examples/hhy_extension_test/config.local.json --write

./build/hhy run extensions/database/examples/hhy_extension_test/transaction.hhy \
  extensions/database/examples/hhy_extension_test/config.local.json --write

database.transaction(config.url, [
    { sql: "INSERT INTO _hhy_transaction_test (id, message) VALUES (?, ?)", params: [1, "created"] },
    { sql: "UPDATE _hhy_transaction_test SET message = ? WHERE id = ?", params: ["committed", 1] }
]) |> print

21.6Current boundaries and troubleshooting

Continue with the extension system internals
Learn about manifest validation, capability declarations, process loading, the Protocol 1 handshake, and extension-author constraints.
/en/learn/extensions-roadmap

22.1What the HTML extension is

The official html 0.2.0 package is a process extension with no network or filesystem effects. Lexbor parses untrusted HTML, evaluates CSS selectors, and extract_report returns batch rows with explicit truncation metadata.

22.2Build and install the HTML extension

brew install jansson lexbor
make -C extensions/html
./build/hhy install ./extensions/html
./build/hhy list

The extension limits input to 768 KiB, keeping protocol messages bounded. extract schema fields use { selector, value: "text" } or { selector, value: "attr", name }; an empty selector reads the current root. It does not return DOM handles: Protocol 1 transports only JSON-shaped values, so html.extract performs parsing and projection inside one extension call.

22.3From HTML extraction to a safe crawler

The static spider composes separate responsibilities: Runtime url_resolve normalizes relative references; the HTML extension discovers links; a depth frontier checks domains, paths, page and queue budgets, and fingerprints before admission; the HTTP layer blocks SSRF at the resolved connection address.

22.4Project one: the my-crawler foundation

make
./practical-projects/my-crawler/init.sh
./practical-projects/my-crawler/self-test.sh
./practical-projects/my-crawler/run.sh

my-crawler is the smallest runnable spider: it reads JSON configuration, recursively discovers authorized links, extracts records, and writes report and failure artifacts. Normal runs reuse ~/.hhy/extensions; CI and self-tests use a temporary HHY_EXTENSION_HOME.

{
  "seeds": ["https://hhylang.dev/zh/learn/cli-reference"],
  "allowed_domains": ["hhylang.dev"],
  "allowed_path_prefixes": ["/zh/learn/"],
  "follow_selector": "main article a[href]",
  "parallelism": 2,
  "max_depth": 2,
  "max_pages": 50,
  "max_frontier": 100,
  "max_links_per_page": 200,
  "allow_private_networks": false,
  "root_selector": "main article h2",
  "max_results": 100,
  "schema": { "title": { "selector": "", "value": "text" } }
}

HHY Collector Framework Crawler Fixture
Pages 3 / 3 Records 3 Failures 0
HHY Collector Framework self-test passed

Read the complete my-crawler source
Start here for configuration, recursive crawling, structured extraction, failure archives, and deterministic tests.
https://github.com/hh696-wq/hhy-vm/tree/main/practical-projects/my-crawler

22.5Project two: the SiteGraph Auditor challenge

SiteGraph Auditor adds a page inventory, normalized graph, metadata audit, and CI quality gate on top of the foundational spider, with both healthy and risky fixtures.

Open the SiteGraph Auditor challenge
Continue with a site graph, content-quality audit, negative SSRF test, and CI gate.
/en/learn/sitegraph-auditor-project

22.6Scope and explicit boundaries

The crawler supports an in-memory or atomically checkpointed frontier, strict configuration-matched resume, and send_to response files. An optional Playwright renderer executes JavaScript separately from the side-effect-free Lexbor extension and applies domain plus DNS private-network checks to documents, redirects, and subresources.

23.1Current release and two future stages

23.2Release lineage, timing, and acceptance gates

Note: these dates are recommended windows, not release commitments.

23.3Evolution principles

Review the roadmap once per quarter. Only unfrozen releases may move; scheduling changes must not weaken published semantics, compatibility commitments, or migration paths.

23.4Explicit non-commitments

• No second Pipe, Stream, or Error model merely to justify a release number.
• No public exposure of internal Runtime C structures without a compatibility strategy.
• No use of recommended windows as a reason to skip testing, security, or cross-platform validation.
• No simultaneous rush into a remote registry, Native ABI, and multiple official extensions before stage gates pass.

24.1HHY Language Support 0.1.0

The editor packages recognize .hhy files and provide HHY syntax highlighting for # comments, shebangs, strings and escapes, Regex, numbers and units, keywords, and operators, plus bracket auto-closing, indentation, and common snippets. VS Code uses a TextMate grammar; Sublime Text uses .sublime-syntax.

Open the editor language-support source ↗
Includes the shared syntax source, generator, VS Code and Sublime Text packages, and real .hhy regression fixtures.
https://github.com/hh696-wq/hhy-vm/tree/main/editors

24.2Generate and verify the packages

git clone https://github.com/hh696-wq/hhy-vm.git
cd hhy-vm/editors
npm install
npm run generate
npm run check
npm run package

The package command creates dist/hhy-language-support-0.1.0.vsix and dist/HHY-0.1.0.sublime-package. The check command compares Lexer keywords and literal suffixes, validates plugin metadata and generated-file freshness, and checks every fixture with the real HHY binary.

24.3Install in VS Code

code --install-extension editors/dist/hhy-language-support-0.1.0.vsix

You can also open Extensions in VS Code and choose Install from VSIX from the top-right menu. After installation, any .hhy file is automatically recognized as HHY.

24.4Install in Sublime Text

Copy editors/dist/HHY-0.1.0.sublime-package into Sublime Text's Installed Packages directory. For development, copy editors/sublime into Packages/HHY. Opening a .hhy file then enables HHY syntax automatically.

25.1Release summary

25.2Data at a glance

25.3Overall baseline and compatibility

The current formal baseline is v1.3.10. Bytecode is default; the AST evaluator remains the semantic oracle and is selectable through --engine ast or HHY_ENGINE=ast. Compiler-produced Stream Kernels must pass their independent Verifier; dynamic and unknown shapes fall back losslessly to general Bytecode.

25.4v1.2.2 release and extension status

Open the HHY Language v1.2.2 release
Download all four platform archives and checksums and read the release notes.
https://github.com/hh696-wq/hhy-vm/releases/tag/v1.2.2

25.5v1.3.7–v1.3.10 Bytecode hardening

Open the HHY Language v1.3.10 release
Four platform archives, per-asset SHA-256, SHA256SUMS, and cache-governance release notes.
https://github.com/hh696-wq/hhy-vm/releases/tag/v1.3.10

25.6Measured performance

Final v1.3.10 CI evidence comes from commit 4ddc8c3 on GitHub Actions Ubuntu 24.04: schema-2 paired/interleaved engine benchmarks plus independent Profiler and cache-decision artifacts. Ratios are Bytecode/AST wall time; lower than one means Bytecode is faster.

25.7v1.3.10 six-runtime same-machine rerun

Rerun on 2026-09-01 on macOS 26.6.2 arm64 with HHY 1.3.10, PHP 8.5.10, Go 1.27.0, Python 3.14.7, Lua 5.5.1, and OpenJDK 26.0.2.1. The fixed task maps, filters, stable-distincts, materializes, and counts one million integers; all six implementations validate output 333334. After two warmups, two independent rounds use seven deterministically shuffled and interleaved fresh processes per runtime. Wall time includes process startup; Go and Java are precompiled and compile time is excluded.

25.8Governance conclusion and watch list

• Overall status: v1.3.10 is formally released; v1.3.7–v1.3.10 semantic, three-path, Profiler, resource, and cache-governance gates are complete.
• Engine policy: Bytecode is default; AST remains permanently available as the semantic oracle, differential-test engine, and --engine ast emergency fallback.
• Performance conclusion: final CI reports 0.3695 for the 1M CPU ratio, 1.0088 for short tasks, 1.0207 for sustained JSON, and 1.0269× Profiler overhead; all gates pass.
• Cache conclusion: compile+verify is not a major cold-run cost; no cache is introduced until new data and a complete threat model trigger review.
• Cross-language conclusion: this same-machine fixed task has Go/Lua/PHP/Java ahead of HHY and HHY ahead of Python; it cannot be generalized to all workloads.
• Update rule: synchronize this report whenever the release baseline, measurement method, engine/cache decision, or overall risk conclusion changes.

Open final v1.3.10 continuous-verification evidence
Four-platform builds, sanitizers, fuzzing, Profiler, cache decision, performance gates, and practical-project acceptance.
https://github.com/hh696-wq/hhy-vm/actions/runs/33497617218