HHY Reference

Standard Library Function Index

Signatures and purposes for all 128 V1.7.1 core callables in the runtime Registry.

Reading the signatures

This page is sourced from the V1.7.1 Runtime Callable Contract Registry and contains all 128 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.

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

funcprint#

print(Value...) -> Null

Write values to stdout; a Stream is consumed and printed item by item.

funcprint_error#

print_error(Value...) -> Null

Write values to stderr for diagnostics.

funcexit#

exit(Int?) -> Never

End the script with an optional status code (default 0) and unwind resources.

funclength#

length(String | List | Map) -> Int

Return String code points or List/Map elements; use count for a Stream.

funcbyte_length#

byte_length(String | BytesBuffer) -> Int

Return the UTF-8 byte count of String or size of BytesBuffer.

functype#

type(Value) -> String

Return a value's logical type name.

funcis_type#

is_type(Value, String) -> Bool

Test whether a value has the named logical type.

functo_int#

to_int(Int | Float | String) -> Int

Explicitly convert Int/Float/String to Int; invalid or overflowing input raises ValueError.

functo_float#

to_float(Int | Float | String) -> Float

Explicitly convert Int/Float/String to Float; invalid input raises ValueError.

funcget#

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

Safely read a List index, Map key, or record field; missing values return null.

funcrequire#

require(Map, String) -> Value

Read a required Map key; missing raises KeyError, while a present null stays null.

funcpick#

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

Return a new Map containing selected keys, preserving present null fields.

funcput#

put(Map, String, Value) -> Map

Return a new Map with one key inserted or replaced; the original is unchanged.

funcremove_key#

remove_key(Map, String) -> Map

Return a new Map without the named key.

funcappend#

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

Return a new List with one item appended.

funcremove_at#

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

Return a new List without the indexed item; out of range raises IndexError.

funcnow#

now() -> DateTime

Return the current zoned DateTime.

funcdatetime.parse#

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

Parse DateTime using an explicit format and timezone; invalid input raises ValueError.

funcrequire_env#

require_env(String) -> String

Read a required environment variable; missing raises KeyError.

funcsleep#

sleep(Duration) -> Null

Wait for a Duration while remaining cancellable.

funccancel#

cancel() -> Never

Trigger the execution's root cancellation token and begin cleanup.

functhrow#

throw(Error) -> Never

Throw an Error through the call stack or Flow.

Flow 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.

funcstream#

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

Convert a List, Map entries, or Range into a lazy single-use Stream.

funcrange#

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

Create an Int Stream from start up to but excluding end.

funcmap#

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

Lazily transform each item one-to-one without automatic flattening.

funcflat_map#

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

Return a child Stream per item and lazily concatenate child streams.

funcwhere#

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

Lazily retain items whose predicate returns Bool true.

functake#

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

Lazily retain the first n items and close upstream early.

funcskip#

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

Lazily discard the first n items and pass the remainder.

funcinspect#

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

Run an observation closure for each item and pass the item unchanged.

funcdistinct#

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

Lazily remove duplicate hashable scalars while retaining a seen set.

funcsort_by#

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

Materialize finite input and stably sort by closure key and asc/desc option.

funcgroup_by#

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

Materialize finite input into Groups containing key and values.

funcdebounce#

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

Coalesce rapid events within a Duration, commonly for watch streams.

funcon_error#

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

On Stream failure, invoke a closure whose returned Stream supplies recovery output.

funcparallel#

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

Process with at most n isolated workers, ordered output, bounded buffering, and fail-fast errors.

funccollect#

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

Consume a finite Stream and materialize it as a List.

funccount#

count(Stream<T>) -> Int

Consume a Stream and return its item count.

funcfirst#

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

Return the first item or null and close upstream early.

funclast#

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

Consume a Stream and return its last item or null.

funcmin#

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

Consume a numeric Stream and return its minimum or null for empty input.

funcmax#

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

Consume a numeric Stream and return its maximum or null for empty input.

funcsum#

sum(Stream<Number>) -> Number

Consume and sum a numeric Stream, respecting Int overflow rules.

funcreduce#

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

Fold a Stream from initial; the closure receives state with acc/item/index.

funcany#

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

Return true on the first matching item and short-circuit upstream.

funcall#

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

Return true only if every item matches; short-circuit on the first false.

funcfor_each#

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

Consume a Stream, execute a closure for each item, and return null.

Text, Regex, JSON, and CSV (18)

funccontains#

contains(String | List, Value) -> Bool

Test whether a String contains a substring or a List contains an equal value.

funcupper#

upper(String) -> String

Return a new String converted to Unicode uppercase.

funclower#

lower(String) -> String

Return a new String converted to Unicode lowercase.

functrim#

trim(String) -> String

Remove whitespace from both ends of a String.

functrim_start#

trim_start(String) -> String

Remove leading whitespace from a String.

functrim_end#

trim_end(String) -> String

Remove trailing whitespace from a String.

funcstarts_with#

starts_with(String, String) -> Bool

Test whether a String starts with the given text.

funcends_with#

ends_with(String, String) -> Bool

Test whether a String ends with the given text.

funcreplace#

replace(String, String, String) -> String

Return a new String with matching text replaced.

funcsplit#

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

Split a String by delimiter text into List<String>.

funcjoin#

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

Join List<String> with delimiter text.

funcregex_match#

regex_match(String, Regex) -> Bool

Test a String against a PCRE2 Regex under regex resource limits.

funcregex_captures#

regex_captures(String, Regex) -> Map | Null

Return full match, byte positions, numbered and named captures; null when unmatched.

funcurl_resolve#

url_resolve(String, String?) -> Map

Resolve an absolute or relative HTTP(S) URL, remove fragments, default ports, and dot segments, and return host, path, and a stable fingerprint.

funcparse_json#

parse_json(String) -> JsonValue

Strictly parse JSON String into ordinary HHY values with line/column errors.

funcencode_json#

encode_json(JsonValue, Map?) -> String

Encode supported ordinary values as JSON; options may enable pretty output.

funcparse_csv#

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

Stream-parse a String or line Stream into Stream<Map>.

funcencode_csv#

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

Stream-encode Stream<Map> into CSV records without line terminators.

Paths, files, and watch (15)

read_* functions read data; write_text, write_bytes, save_text, and save_lines use a sibling temporary file plus atomic replacement. append_text appends to the target. Dry-run intercepts filesystem actions.

funcpath#

path(String) -> Path

Lexically normalize String into Path without filesystem access.

funcpath_join#

path_join(Path, String | Path) -> Path

Combine a Path with a child path and return a normalized Path.

funcfiles#

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

Lazily walk a root with a glob and return a File/Directory Stream.

funcread_text#

read_text(Path) -> String

Read an entire UTF-8 file as String.

funcread_lines#

read_lines(Path) -> Stream<String>

Lazily read UTF-8 lines with terminators removed.

funcread_bytes#

read_bytes(Path) -> BytesBuffer

Read an entire binary file as BytesBuffer.

funcwrite_text#

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

Atomically replace with String, supporting overwrite/create_parents.

funcappend_text#

append_text(Path, String) -> Path

Append String to the end of a file.

funcwrite_bytes#

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

Atomically replace a file with BytesBuffer.

funcsave_text#

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

Atomically save a String or pull a text Stream directly to disk.

funcsave_lines#

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

Write a String Stream with LF per item and atomically replace the target.

funccopy#

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

Copy a file with atomic no-replace; the target parent directory must already exist.

funcmove#

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

Move or rename a file while respecting overwrite options.

funcremove#

remove(Path) -> Path

Remove an explicit Path and return it.

funcwatch#

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

Return an infinite FileEvent Stream with recursive option and cancellation.

Processes, 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.

funcrun#

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

Execute argv directly without a shell and return CommandResult.

funcshell#

shell(String, Map?) -> CommandResult

Explicitly execute a String through a shell for redirects, pipes, and shell syntax.

funcstdout_lines#

stdout_lines(CommandResult) -> Stream<String>

Expose CommandResult.stdout as a lazy line Stream.

funcprocesses#

processes() -> Stream<Process>

Return a Stream<Process> snapshot of current processes.

funcstdin_lines#

stdin_lines() -> Stream<String>

Lazily read stdin lines until EOF or cancellation.

funcevery#

every(Duration) -> Stream<Int>

Produce an infinite timer tick Stream at a Duration interval.

HTTP (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.

funchttp.get#

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

Build a GET HttpRequest plan without network I/O.

funchttp.post#

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

Build a POST HttpRequest plan without network I/O.

funchttp.put#

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

Build a PUT HttpRequest plan without network I/O.

funchttp.delete#

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

Build a DELETE HttpRequest plan without network I/O.

functimeout#

timeout(HttpRequest, Duration) -> HttpRequest

Return a new HttpRequest with its timeout configured.

funcretry#

retry(HttpRequest, Map) -> HttpRequest

Return a new HttpRequest configured with retry count and backoff.

funcsend#

send(HttpRequest) -> HttpResponse

Perform the HttpRequest network effect and return HttpResponse.

funcsend_to#

send_to(HttpRequest, Path) -> HttpResponse

Stream the HTTP body into an atomic file and return an HttpResponse with path and size.

funcresponse_body#

response_body(HttpResponse) -> String

Validate response status and decode the bounded body as UTF-8 String.

funcresponse_bytes#

response_bytes(HttpResponse) -> BytesBuffer

Validate response status and return the bounded binary BytesBuffer.

Web Runtime (25)

web.* builds persistent applications, responses, middleware, and production endpoints; only web.listen binds a network port.

funcweb.app#

web.app() -> WebApp

Create a Web application.

funcweb.get#

web.get(WebApp, String, Function) -> WebApp

funcweb.post#

web.post(WebApp, String, Function) -> WebApp

funcweb.put#

web.put(WebApp, String, Function) -> WebApp

funcweb.patch#

web.patch(WebApp, String, Function) -> WebApp

funcweb.delete#

web.delete(WebApp, String, Function) -> WebApp

funcweb.use#

web.use(WebApp, Function) -> WebApp

Append short-circuiting middleware.

funcweb.static#

web.static(WebApp, String, Path) -> WebApp

Mount a secure static directory.

funcweb.cors#

web.cors(WebApp, Map?) -> WebApp

Enable CORS and OPTIONS preflight.

funcweb.request_id#

web.request_id(WebApp) -> WebApp

Enable request IDs.

funcweb.health#

web.health(WebApp, String?) -> WebApp

Enable the health endpoint.

funcweb.trust_proxy#

web.trust_proxy(WebApp) -> WebApp

Trust the proxy-provided client address.

funcweb.text#

web.text(String, Map?) -> WebResponse

Create a text response.

funcweb.html#

web.html(String, Map?) -> WebResponse

Create an HTML response.

funcweb.json#

web.json(JsonValue, Map?) -> WebResponse

Create a JSON response.

funcweb.redirect#

web.redirect(String, Map?) -> WebResponse

Create a redirect response.

funcweb.response#

web.response(Map) -> WebResponse

Create a response from an options Map.

funcweb.multipart#

web.multipart(WebRequest, Path?) -> Map

Parse bounded multipart forms and uploads.

funcweb.stream#

web.stream(Stream, Map?) -> WebResponse

Create a backpressured streaming response.

funcweb.sse#

web.sse(Stream<String>) -> WebResponse

Create a Server-Sent Events response.

funcweb.sign_cookie#

web.sign_cookie(String, String) -> String

HMAC-sign a cookie value.

funcweb.verify_cookie#

web.verify_cookie(String, String) -> String | Null

Verify and read a signed cookie.

funcweb.metrics#

web.metrics(WebApp, String?) -> WebApp

Enable the Prometheus metrics endpoint.

funcweb.gzip#

web.gzip(WebApp) -> WebApp

Enable gzip negotiation through Accept-Encoding.

funcweb.listen#

web.listen(WebApp, Map?) -> Null

Start the bounded HTTP/1.1 server.

Controlled concurrency (7, experimental and disabled by default)

funcatomic_state#

atomic_state(data)

Create state owned by one Runtime/PID. Experimental; disabled by default.

funcatomic_read#

atomic_read(state)

Read an immutable snapshot. Experimental; disabled by default.

funcatomic_update#

atomic_update(state, callback)

Validate a pure callback candidate and publish synchronously; precommit errors preserve the old value. Experimental; disabled by default.

funcatomic_close#

atomic_close(state)

Close the handle; later access and repeated close fail. Experimental; disabled by default.

funcatomic_file_update#

atomic_file_update(path, timeout, callback)

Read and replace an existing regular file under a cooperative lock; timeout bounds lock waiting only. Experimental; disabled by default.

functransaction_strict#

transaction_strict(config, options?, callback)

Bind SQL to the current tx; caught errors still prevent commit; reconcile unknown commits. Experimental; disabled by default.

functask_map#

task_map(data, parallelism, result_limit, callback)

Execute isolated processes, return an ordered List, and bound direct children and accepted results. Experimental; disabled by default.

Read the complete guide and examplesIncludes the guarantee matrix, failure handling and actual validation evidence