HHY Reference

Standard Library Function Index

Signatures and purposes for all 94 V1.0 callables in the runtime Registry.

Reading the signatures

This page is sourced from the V1.0 Runtime Callable Contract Registry and contains all 94 entries. 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 (17)

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.

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_* functions write directly, and save_* functions use a temporary file plus atomic replacement. 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 and parent creation options.

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 (9)

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.

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.