EigenScript Standard Library

The standard library lives in lib/. Libraries are pure EigenScript — no C extensions required.

Loading Libraries

load_file of "lib/math.eigs"
load_file of "lib/list.eigs"

Path resolution order:

Relative to the current working directory
Relative to the script file's directory
Relative to the script file's parent directory
Relative to the EigenScript executable's parent directory
Relative to the installed stdlib beside the executable
Relative to ~/.local/lib/eigenscript

This means load_file of "lib/math.eigs" works whether you run the script from the project root, from an external project while using a source tree binary, or from an installed binary.

Calling Convention

EigenScript functions take one argument, n. Libraries follow two patterns:

Single argument — n is the value directly:

abs of -5             # n is -5
reverse of [1, 2, 3]  # n is the list [1, 2, 3]

Multiple arguments — pass a list, unpack n[0], n[1]:

clamp of [15, 0, 10]         # n[0]=15, n[1]=0, n[2]=10
map of [items, double_fn]    # n[0]=items, n[1]=double_fn

The difference: does the function need one thing or several? Check the signature comment above each function (e.g., # clamp of [value, lo, hi]).

Module Index

lib/math.eigs — Numeric Utilities

Function	Signature	Description
`abs`	`abs of value`	Absolute value
`sign`	`sign of value`	Returns -1, 0, or 1
`max_val`	`max_val of list`	Maximum element
`min_val`	`min_val of list`	Minimum element
`clamp`	`clamp of [value, lo, hi]`	Restrict to range
`lerp`	`lerp of [a, b, t]`	Linear interpolation
`dot`	`dot of [list_a, list_b]`	Dot product
`gcd`	`gcd of [a, b]`	Greatest common divisor
`lcm`	`lcm of [a, b]`	Least common multiple
`argmax`	`argmax of list`	Index of the largest element (first on ties, -1 if empty)
`argmin`	`argmin of list`	Index of the smallest element (first on ties, -1 if empty)

lib/list.eigs — Functional List Operations

Function	Signature	Description
`map`	`map of [list, fn]`	Apply fn to each element
`filter`	`filter of [list, fn]`	Keep elements where fn is truthy
`reduce`	`reduce of [list, fn, init]`	Fold left with initial value
`reverse`	`reverse of list`	Reverse a list
`zip`	`zip of [list_a, list_b]`	Pair elements from two lists
`flatten`	`flatten of list`	Flatten one level of nesting
`take`	`take of [list, n]`	First n elements (clamps to length)
`drop`	`drop of [list, n]`	All but the first n elements
`any`	`any of [list, fn]`	1 if fn is truthy for some element, else 0 (empty: 0)
`all`	`all of [list, fn]`	1 if fn is truthy for every element, else 0 (empty: 1)
`find_index`	`find_index of [list, fn]`	Index of first element where fn is truthy, or -1
`partition`	`partition of [list, fn]`	Split into `[passing, failing]` in one pass
`group_by`	`group_by of [list, key_fn]`	Bucket elements into a dict by stringified key
`deep_flatten`	`deep_flatten of list`	Fully flatten nested lists (recursive)
`count_of`	`count_of of [list, val]`	Count occurrences of a value (`==` equality)
`frequencies`	`frequencies of list`	Distribution of values as a dict (stringified keys)

Higher-order functions take EigenScript functions as arguments:

load_file of "lib/list.eigs"

define double as:
    return n * 2

define is_even as:
    return (n % 2) == 0

define add_fn as:
    return n[0] + n[1]

doubled is map of [[1,2,3], double]      # [2, 4, 6]
evens is filter of [[1,2,3,4], is_even]  # [2, 4]
total is reduce of [[1,2,3], add_fn, 0]  # 6

lib/string.eigs — String Utilities

Function	Signature	Description
`join`	`join of [list, separator]`	Join elements with separator
`repeat`	`repeat of [string, count]`	Repeat string n times
`pad_left`	`pad_left of [string, width, char]`	Left-pad to width
`pad_right`	`pad_right of [string, width, char]`	Right-pad to width
`capitalize`	`capitalize of string`	Uppercase the first character, leave the rest
`replace_all`	`replace_all of [string, find, replacement]`	Replace every occurrence of `find`

lib/text_builder.eigs — Buffered Text Assembly

text_builder_* functions are root-backed builtins exposed through this load-compatible stdlib module. Builders use a native growable text buffer while keeping the original stdlib API.

Function	Signature	Description
`text_builder_new`	`text_builder_new of null`	Create a native mutable text builder
`text_builder_append`	`text_builder_append of [builder, value]`	Append one value as text
`text_builder_append_line`	`text_builder_append_line of [builder, value]`	Append one value and a newline
`text_builder_extend`	`text_builder_extend of [builder, values]`	Append each item in a list
`text_builder_part_count`	`text_builder_part_count of builder`	Count appended parts
`text_builder_to_string`	`text_builder_to_string of builder`	Render buffered text
`text_builder_clear`	`text_builder_clear of builder`	Empty a builder for reuse

lib/int_vector.eigs - Fixed-Size Integer Vectors

int_vector functions return EigenScript buffers, so vectors support direct indexing (vec[i]), indexed assignment (vec[i] is value), len, and iteration.

Function	Signature	Description
`int_vector_new`	`int_vector_new of count`	Create a zero-filled integer vector
`int_vector_filled`	`int_vector_filled of [count, value]`	Create an integer vector filled with one value
`int_vector_fill`	`int_vector_fill of [vec, value]`	Overwrite every slot with one value
`int_vector_from_list`	`int_vector_from_list of list`	Convert a numeric list to an integer vector
`int_vector_to_list`	`int_vector_to_list of vec`	Convert an integer vector to a list
`int_vector_clone`	`int_vector_clone of vec`	Copy a vector into a new buffer
`int_vector_copy`	`int_vector_copy of [src, src_off, dst, dst_off, count]`	Copy a range between vectors
`int_vector_len`	`int_vector_len of vec`	Return vector length
`int_vector_get`	`int_vector_get of [vec, index]`	Explicit indexed read
`int_vector_set`	`int_vector_set of [vec, index, value]`	Explicit indexed write

lib/sanitize.eigs — Text Validation

Function	Signature	Description
`sanitize_text`	`sanitize_text of string`	Trim whitespace
`is_garble`	`is_garble of string`	1 if text looks like nonsense
`clean_response`	`clean_response of string`	Trim at "User:" marker
`check_openai`	`check_openai of null`	1 if OpenAI API key available

lib/auth.eigs — Token Authentication

Function	Signature	Description
`auth_login`	`auth_login of password`	Verify password, set session token
`auth_check`	`auth_check of token`	1 if token is valid
`auth_logout`	`auth_logout of null`	Clear session
`auth_get_token`	`auth_get_token of null`	Return current token
`require_auth`	`require_auth of null`	Check auth from HTTP headers

Requires: env_get, random_hex, http_request_headers builtins.

lib/observer.eigs — Observer Utilities

Function	Signature	Description
`entropy_of`	`entropy_of of value`	Current entropy
`delta_of`	`delta_of of value`	Current dH (rate of change)
`prev_delta_of`	`prev_delta_of of value`	Previous dH
`is_converged`	`is_converged of value`	1 if converged
`is_stable`	`is_stable of value`	1 if stable or converged
`is_improving`	`is_improving of value`	1 if entropy decreasing
`is_diverging`	`is_diverging of value`	1 if entropy increasing
`is_oscillating`	`is_oscillating of value`	1 if dH sign-flipping
`wait_until_converged`	`wait_until_converged of [val, fn, max]`	Run fn until convergence
`track_regimes`	`track_regimes of [val, fn, max]`	Log regime transitions
`threshold_alert`	`threshold_alert of [val, lo, hi]`	"below", "above", or "ok"
`snapshot`	`snapshot of value`	[value, status, entropy, dH, prev_dH]

lib/tensor.eigs — Tensor Convenience Wrappers

Function	Signature	Description
`xavier_init`	`xavier_init of [rows, cols]`	Xavier/Glorot initialization
`he_init`	`he_init of [rows, cols]`	He/Kaiming initialization
`ones`	`ones of [rows, cols]`	Tensor of ones
`linear`	`linear of [input, W, bias]`	Affine transform x@W + b
`mse_loss`	`mse_loss of [pred, target]`	Mean squared error
`cross_entropy_loss`	`cross_entropy_loss of [logits, idx]`	Cross-entropy loss
`accuracy`	`accuracy of [logits_list, labels]`	Classification accuracy
`normalize`	`normalize of tensor`	Zero-mean, unit-variance
`clip`	`clip of [tensor, lo, hi]`	Clamp elements
`l2_norm`	`l2_norm of tensor`	Euclidean norm
`scale`	`scale of [tensor, scalar]`	Scalar multiplication

lib/bcd.eigs — Packed BCD Codec

from_bcd of 0x26 → 26, to_bcd of 59 → 0x59 — any width, each hex nibble a decimal digit. Invalid nibbles, negatives, and fractions raise (a torn RTC register read must fail loudly, not decode to a plausible number). Consumers: CMOS RTC registers, the Game Boy's DAA.

lib/harness.eigs — Count-and-Continue Test Scaffolding

harness.start of "MARKER" / harness.check of [tag, got, want] / harness.check_true / harness.finish of [] — every check prints and COUNTS (one failure never hides the rest), finish prints MARKER_ALL_PASS on success or throws with the tally. The twin-gate pattern extracted from six hand-rolled EigenOS harnesses.

lib/observer_slots.eigs — Observe a Dynamic Collection

observer_slots.feed of [i, v] / is_stable of i / is_diverging of i / verdict of i (the full regime string) — eight NAMED scalar slots behind index dispatch, because observer trajectories key to named bindings and stable of xs[i] can never accumulate one (#262). Feed forces fresh values; slot 9 throws (silently-unobserved is the failure mode this prevents). Feed bounded signatures, not raw counters (the #294 flat-entropy band).

lib/datetime.eigs — Dates, Times, Durations

Two halves. The clock/timer functions shell out to system date and are host-profile only:

Function	Signature	Description
`now`	`now of null`	Current date and time string
`today`	`today of null`	Current date string
`timestamp`	`timestamp of null`	Unix epoch seconds
`iso_date`	`iso_date of null`	ISO 8601 timestamp
`elapsed`	`elapsed of [start, end]`	Human-readable duration
`elapsed_ms`	`elapsed_ms of [start, end]`	Duration in milliseconds
`sleep_ms`	`sleep_ms of ms`	Pause execution
`year` / `month` / `day`	`year of null` (etc.)	Current field
`weekday`	`weekday of null`	Day-of-week name
`timer_start`	`timer_start of null`	Capture start timestamp
`timer_elapsed`	`timer_elapsed of start`	Seconds since start
`format_date`	`format_date of fmt`	strftime format string

The civil-math functions are pure and run on every profile: days_from_civil of [y, m, d] / civil_from_days of days (day 0 = 1970-01-01, proleptic Gregorian), weekday_from_days of days (0=Sunday), epoch_from_civil of [y, m, d, hh, mm, ss] / civil_from_epoch of secs. A bare-metal RTC driver turns CMOS registers into epoch seconds with these and no host clock.

lib/io.eigs — File and Data Helpers

Function	Signature	Description
`read_lines`	`read_lines of "path"`	File to list of lines
`write_lines`	`write_lines of ["path", lines]`	List of lines to file
`read_csv`	`read_csv of "path.csv"`	CSV to list of lists
`write_csv`	`write_csv of ["path.csv", rows]`	List of lists to CSV
`file_copy`	`file_copy of ["src", "dst"]`	Copy file contents
`slurp`	`slurp of "path"`	Read with existence check

lib/json.eigs — JSON Manipulation

Function	Signature	Description
`json_get`	`json_get of [json, "key"]`	Extract top-level value
`json_get_path`	`json_get_path of [json, "a.b"]`	Extract nested value
`json_has`	`json_has of [json, "key"]`	1 if key exists
`json_from_pairs`	`json_from_pairs of pairs`	[[k,v],...] to JSON
`json_merge`	`json_merge of [json_a, json_b]`	Merge two objects
`json_pretty`	`json_pretty of json_str`	Indented output

lib/test.eigs — Test Runner

Function	Signature	Description
`assert_eq`	`assert_eq of [actual, expected, desc]`	Exact equality
`assert_near`	`assert_near of [actual, expected, tol, desc]`	Approximate equality
`assert_true`	`assert_true of [cond, desc]`	Truthy check
`assert_false`	`assert_false of [cond, desc]`	Falsy check
`test_summary`	`test_summary of null`	Print results, exit on failure

lib/format.eigs — Number Formatting and Tables

Function	Signature	Description
`fmt_num`	`fmt_num of [value, decimals]`	Fixed decimal places
`fmt_percent`	`fmt_percent of [value, decimals]`	Format as percentage
`fmt_bar`	`fmt_bar of [val, max, width]`	Text progress bar
`fmt_padded`	`fmt_padded of [value, width]`	Right-aligned field
`fmt_table`	`fmt_table of [headers, rows]`	Aligned text table

lib/checksum.eigs — Byte Integrity

crc32 of data, adler32 of data, sum8 of data — over a string or a buffer (bytes 0..255); results are unsigned 32-bit numbers. CRC-32 is the reflected 0xEDB88320 polynomial (zlib/PNG/ethernet), Adler-32 is zlib's. Written once so storage layers, cartridge headers, and network frames stop hand-rolling integrity math.

load_file of "lib/checksum.eigs"
print of (crc32 of "123456789")      # 3421780262
print of (adler32 of "Wikipedia")    # 300286872

format.eigs also ships hexdump of data (string or buffer → classic offset/hex/ascii rows), and functional.eigs ships wait_until of [pred, tries, sleep_fn] — the bounded-poll shape every IRQ drain and readiness check re-derives.

lib/sort.eigs — Sorting Utilities

Function	Signature	Description
`sort_asc`	`sort_asc of list`	Sort ascending
`sort_desc`	`sort_desc of list`	Sort descending
`sort_by`	`sort_by of [list, key_fn]`	Sort by key function
`sorted_indices`	`sorted_indices of list`	Indices that would sort the list
`is_sorted`	`is_sorted of list`	1 if ascending order
`unique`	`unique of list`	Sorted, deduplicated list

lib/map.eigs — Key-Value Data Structure

Maps are lists of [key, value] pairs. Keys are compared with ==.

Function	Signature	Description
`map_new`	`map_new of null`	Create empty map
`map_get`	`map_get of [map, key]`	Get value or null
`map_get_default`	`map_get_default of [map, key, default]`	Get value or default
`map_has`	`map_has of [map, key]`	1 if key exists
`map_set`	`map_set of [map, key, value]`	Set key (returns new map)
`map_remove`	`map_remove of [map, key]`	Remove key (returns new map)
`map_keys`	`map_keys of map`	List all keys
`map_values`	`map_values of map`	List all values
`map_size`	`map_size of map`	Number of entries
`map_from_lists`	`map_from_lists of [keys, values]`	Build from parallel lists
`map_merge`	`map_merge of [map_a, map_b]`	Merge (second wins)
`map_entries`	`map_entries of map`	List of [key, value] pairs

load_file of "lib/map.eigs"

m is map_new of null
m is map_set of [m, "lang", "EigenScript"]
m is map_set of [m, "version", "0.5"]
print of (map_get of [m, "lang"])       # "EigenScript"
print of (map_keys of m)                # ["lang", "version"]

lib/functional.eigs — Composition and Higher-Order Utilities

Function	Signature	Description
`identity`	`identity of x`	Return argument unchanged
`constantly`	`constantly of x`	Return value (sentinel pattern)
`chain`	`chain of [fn_list, value]`	Pipeline: apply left to right
`apply_all`	`apply_all of [fn_list, value]`	Apply each fn, collect results
`juxt`	`juxt of [fn_list, value]`	Alias for apply_all
`complement`	`complement of [pred, value]`	Negate predicate result
`apply_when`	`apply_when of [pred, fn, value]`	Apply fn if pred is truthy
`unless`	`unless of [pred, fn, value]`	Apply fn if pred is falsy
`times`	`times of [count, fn]`	Call fn(i) for i in 0..count-1
`iterate`	`iterate of [fn, value, count]`	Apply fn n times

load_file of "lib/functional.eigs"

define double as:
    return n * 2

define square as:
    return n * n

# Pipeline: double then square
result is chain of [[double, square], 3]   # square(double(3)) = 36

# Apply multiple functions to same value
results is apply_all of [[double, square], 5]  # [10, 25]

The UI Toolkit — lib/ui*.eigs

A widget toolkit over the gfx extension, split across focused modules: lib/ui.eigs (core + the _ui shared-state dict — the reference pattern for cross-file module state), lib/ui_layout.eigs, lib/ui_draw.eigs, lib/ui_theme.eigs, lib/ui_focus.eigs, lib/ui_anim.eigs, lib/ui_dnd.eigs, lib/ui_registry.eigs, and the widget families lib/ui_w_basic.eigs, lib/ui_w_button.eigs, lib/ui_w_container.eigs, lib/ui_w_data.eigs, lib/ui_w_dialog.eigs, lib/ui_w_input.eigs, lib/ui_w_menu.eigs, lib/ui_w_slider.eigs, lib/ui_w_special.eigs, lib/ui_w_viz.eigs. Start from lib/ui.eigs's header; the modules document their own widget signatures.

lib/invariant.eigs — Runtime Invariant Checks

Declare-and-check invariants inside programs; see the module header for the assertion forms.

lib/contract.eigs — Trajectory Contracts

Machine-checked convergence/stability properties — the observer-native answer to "what replaces static types here." require/ensure are plain predicates; the trajectory contracts drive a seed through a one-arg step function and assert a property of the resulting trajectory.

Function	Signature	Description
`require`	`require of [cond, msg]`	Precondition; throws unless `cond` is truthy
`ensure`	`ensure of [cond, msg]`	Postcondition; throws unless `cond` is truthy
`expect_converging`	`expect_converging of [x0, step_fn, max_obs, msg]`	Throws unless the trajectory settles within `max_obs` (value channel)
`expect_monotone`	`expect_monotone of [x0, step_fn, max_obs, msg]`	Throws on a sign-flipping (oscillating) value trajectory
`invariant_stable`	`invariant_stable of [x0, step_fn, max_obs, msg]`	Throws if the value ever begins moving or oscillating

Convergence is read on the value channel, not entropy (a monotonically exploding value reads converged on the entropy channel — the #294 blind spot). Convergence is not correctness: pair with ensure on the final residual. See docs/OBSERVER.md "Contracts" and examples/stem/contract_solver.eigs.

lib/utf8.eigs — UTF-8 Codepoints over Byte Strings

str is a byte string (docs/SPEC.md "Text"); this module gives character semantics when you need them, decoding UTF-8 over the byte primitives.

Function	Signature	Description
`utf8_len`	`utf8_len of s`	Number of codepoints
`utf8_codepoints`	`utf8_codepoints of s`	List of codepoint numbers
`utf8_at`	`utf8_at of [s, i]`	i-th codepoint (0-indexed), or -1
`utf8_char_at`	`utf8_char_at of [s, i]`	i-th character as a (multi-byte) string, or ""
`utf8_validate`	`utf8_validate of s`	1 if structurally valid UTF-8, else 0
`utf8_encode`	`utf8_encode of cp`	Codepoint → UTF-8 byte string ("" if unencodable)
`utf8_from_codepoints`	`utf8_from_codepoints of cps`	List of codepoints → UTF-8 string (inverse of `utf8_codepoints`)

lib/pkg.eigs — Package Manager Runtime

The --pkg machinery's script half (eigs.json, SHA-pinned lockfiles); used by the package tooling rather than imported directly.

lib/test_runner.eigs — Suite Runner

Drives multi-file test suites (used with lib/test.eigs); prints per-file and total tallies.

lib/args.eigs — CLI Argument Parsing

Function	Signature	Description
`parse_args`	`parse_args of null`	Parse CLI args into map
`get_flag`	`get_flag of [parsed, "--flag"]`	1 if flag present
`get_opt`	`get_opt of [parsed, "--key", default]`	Get option or default
`get_positional`	`get_positional of parsed`	List of positional args
`has_flag`	`has_flag of [parsed, "--flag"]`	Alias for get_flag
`require_opt`	`require_opt of [parsed, "--key", usage]`	Get option or exit

load_file of "lib/args.eigs"
# eigenscript myscript.eigs --verbose --output=result.txt input.csv
parsed is parse_args of null
if (get_flag of [parsed, "--verbose"]) == 1:
    print of "Verbose mode on"
outfile is get_opt of [parsed, "--output", "out.txt"]
files is get_positional of parsed    # ["input.csv"]

lib/config.eigs — Configuration File Loading

Function	Signature	Description
`load_env_file`	`load_env_file of ".env"`	Parse KEY=VALUE file
`load_ini`	`load_ini of "config.ini"`	Parse INI config
`config_get`	`config_get of [cfg, key, default]`	Get with default
`config_require`	`config_require of [cfg, key]`	Get or exit
`env_or`	`env_or of ["VAR", default]`	Env var with fallback
`config_keys`	`config_keys of cfg`	List all keys
`config_section`	`config_section of [cfg, "section"]`	Get section keys

lib/set.eigs — Set Operations

Sets are sorted lists with no duplicates.

Function	Signature	Description
`set_from`	`set_from of list`	Create set from list
`set_has`	`set_has of [set, value]`	1 if member
`set_add`	`set_add of [set, value]`	Add element
`set_remove`	`set_remove of [set, value]`	Remove element
`set_size`	`set_size of set`	Element count
`union`	`union of [a, b]`	All from both
`intersect`	`intersect of [a, b]`	Common elements
`difference`	`difference of [a, b]`	In a, not in b
`symmetric_diff`	`symmetric_diff of [a, b]`	In one, not both
`is_subset`	`is_subset of [a, b]`	1 if a ⊆ b
`is_superset`	`is_superset of [a, b]`	1 if a ⊇ b
`set_equal`	`set_equal of [a, b]`	1 if same elements

lib/log.eigs — Structured Logging

Function	Signature	Description
`log_level`	`log_level of "debug"`	Set minimum level
`log_debug`	`log_debug of msg`	Debug message
`log_info`	`log_info of msg`	Info message
`log_warn`	`log_warn of msg`	Warning message
`log_error`	`log_error of msg`	Error message
`log_msg`	`log_msg of ["level", msg]`	Log with named level

Levels: debug < info < warn < error < silent. Default: info.

lib/validate.eigs — Input Validation

Function	Signature	Description
`is_nonempty`	`is_nonempty of value`	Non-empty string/list
`is_number`	`is_number of value`	Numeric or parseable
`is_integer`	`is_integer of value`	Whole number
`in_range`	`in_range of [val, lo, hi]`	Within bounds
`is_one_of`	`is_one_of of [val, list]`	Value in allowed list
`is_email`	`is_email of string`	Basic email format
`is_alpha`	`is_alpha of string`	Letters only
`is_alphanumeric`	`is_alphanumeric of string`	Letters and digits
`is_url`	`is_url of string`	Basic URL format
`validate_all`	`validate_all of checks`	Run multiple checks

lib/http.eigs — HTTP Client and Server Helpers

Requires full build for server builtins. Client uses exec_capture + curl. Client helpers only allow http:// and https:// URLs; rejected URLs return [-1, ""].

Function	Signature	Description
`http_get`	`http_get of url`	GET request
`http_post_json`	`http_post_json of [url, data]`	POST JSON
`route_get`	`route_get of [path, handler]`	Register GET route
`route_post`	`route_post of [path, handler]`	Register POST route
`json_response`	`json_response of data`	Build JSON response
`text_response`	`text_response of string`	Build text response
`error_response`	`error_response of [code, msg]`	Build error response
`parse_query`	`parse_query of string`	Parse query string
`start_server`	`start_server of port`	Bind and serve

lib/queue.eigs — Queue, Stack, and Priority Queue

All structures are immutable — operations return new structures.

Function	Signature	Description
`queue_new`	`queue_new of null`	New FIFO queue
`enqueue`	`enqueue of [q, item]`	Add to back
`dequeue`	`dequeue of q`	[item, rest] from front
`peek`	`peek of q`	Front item
`stack_new`	`stack_new of null`	New LIFO stack
`push`	`push of [s, item]`	Push to top
`pop`	`pop of s`	[item, rest] from top
`stack_peek`	`stack_peek of s`	Top item
`pq_new`	`pq_new of null`	New priority queue
`pq_push`	`pq_push of [pq, priority, item]`	Insert with priority
`pq_pop`	`pq_pop of pq`	[item, rest] (min first)
`pq_peek`	`pq_peek of pq`	Lowest-priority item

lib/state.eigs — Finite State Machine

Function	Signature	Description
`sm_new`	`sm_new of "initial"`	Create state machine
`sm_add_transition`	`sm_add_transition of [sm, from, event, to]`	Add rule
`sm_send`	`sm_send of [sm, event]`	Trigger transition
`sm_try_send`	`sm_try_send of [sm, event]`	Trigger or no-op
`sm_can_send`	`sm_can_send of [sm, event]`	1 if valid
`sm_state`	`sm_state of sm`	Current state
`sm_history`	`sm_history of sm`	State history
`sm_is`	`sm_is of [sm, "state"]`	Check current state
`sm_reset`	`sm_reset of sm`	Reset to initial
`sm_available_events`	`sm_available_events of sm`	Valid events
`sm_transitions_from`	`sm_transitions_from of [sm, state]`	Transitions list

load_file of "lib/state.eigs"
sm is sm_new of "idle"
sm is sm_add_transition of [sm, "idle", "start", "running"]
sm is sm_add_transition of [sm, "running", "stop", "idle"]
sm is sm_add_transition of [sm, "running", "error", "failed"]
sm is sm_send of [sm, "start"]
print of (sm_state of sm)              # "running"
print of (sm_can_send of [sm, "stop"]) # 1

lib/template.eigs — String Templating

{% raw %}

Function	Signature	Description
`render`	`render of [template, vars]`	Interpolate `{{key}}`
`render_file`	`render_file of [path, vars]`	Load and render
`render_lines`	`render_lines of [template, vars]`	Render to line list
`render_each`	`render_each of [template, items, key]`	Render per item
`render_block`	`render_block of [template, vars, cond]`	Conditional render
`fill`	`fill of [template, key, value]`	Single-variable shorthand

load_file of "lib/template.eigs"
vars is [["name", "World"], ["version", "0.5"]]
msg is render of ["{{name}} is running v{{version}}", vars]
print of msg   # "World is running v0.5"

{% endraw %}

lib/eigen.eigs — Meta-Circular Interpreter

Function	Signature	Description
`eigen_tokenize`	`eigen_tokenize of source`	Tokenize source string into token list
`eigen_parse`	`eigen_parse of tokens`	Parse token list into AST
`eigen_eval`	`eigen_eval of [ast, env]`	Evaluate AST in environment, return value
`eigen_run`	`eigen_run of source`	Evaluate source string end-to-end

load_file of "lib/eigen.eigs"
tokens is eigen_tokenize of "x is 2 + 3"
ast is eigen_parse of tokens
result is eigen_run of "x is 2 + 3"

Writing Library Functions

Follow these conventions:

Header: Use the standard format with # ==== borders, module name, and complete usage examples.
Signature comment: Add # func_name of args -> return_type above each function definition.
Naming: Use snake_case. Prefer clear names over short ones.
Validation: Check for empty lists where relevant. Return a sensible default (0, empty list, empty string) rather than crashing.
No side effects: Library functions should return values, not print. Exception: auth/sanitize modules that manage state.

Example:

# ---- my_func: description of what it does ----
# my_func of [arg1, arg2] -> return_type
define my_func as:
    a is n[0]
    b is n[1]
    # ... implementation ...
    return result

STEM Libraries (0.9.2+)

lib/physics.eigs

14 CODATA constants, 80+ functions: kinematics, projectile motion, forces, energy, waves, thermodynamics, electromagnetism, optics, special relativity, nuclear/quantum, fluid mechanics.

lib/chemistry.eigs

Periodic table (36 elements H–Kr), molecular weight parser, stoichiometry, gas laws, acids/bases (pH, Henderson-Hasselbalch), thermochemistry (Gibbs, Nernst), solution properties.

lib/biology.eigs

Population dynamics, genetics (Hardy-Weinberg, Punnett squares), molecular biology (DNA complement, transcription, full 64-codon table, translation), enzyme kinetics (Michaelis-Menten), ecology (Shannon/Simpson diversity).

lib/engineering.eigs

Unit conversions, signal processing (DFT/IDFT, convolution, spectrum), control systems (PID), structural (beam deflection, Euler buckling), electrical (impedance, resonance, voltage/current dividers).

lib/earth_science.eigs

Atmospheric science (barometric formula, wind chill), seismology (Richter), oceanography (wave speed, seawater density), astronomy (Kepler, escape velocity, Schwarzschild radius, stellar luminosity), climate (CO2 forcing).

lib/linalg.eigs

Matrix operations (transpose, multiply, determinant, inverse via Gauss- Jordan), vector algebra (dot, cross, norm, project), linear system solver, least squares, 2×2 eigenvalues/eigenvectors.

lib/calculus.eigs

Numerical differentiation (central difference, gradient), integration (trapezoidal, Simpson's, Monte Carlo), root finding (bisection, Newton- Raphson, secant), ODEs (Euler, RK4 scalar and system), Taylor series, interpolation (Lagrange, linear).

lib/probability.eigs

Combinatorics (factorial, C(n,k), P(n,k)), distributions (binomial, Poisson, normal, exponential, uniform), Bayesian inference, expected value, chi-squared statistic.

lib/optimize.eigs — Observer-Aware

Gradient descent with observer-adaptive learning rate, multi-variable optimization, simulated annealing, golden section search, genetic algorithm. All use report of loss for automatic convergence detection.

lib/simulation.eigs — Observer-Aware

Generic equilibrium detector, stability analyzer, spring-mass-damper, Lotka-Volterra predator-prey, 1D heat equation. Observer detects equilibrium, oscillation, and convergence.

lib/numerics.eigs — Observer-Aware

Jacobi/Gauss-Seidel iterative solvers, power iteration for eigenvalues, fixed-point iteration. Observer detects residual convergence.

lib/experiment.eigs — Observer-Aware

Measurement stability tracking, entropy spike outlier detection, convergence rate estimation, behavioral regime detection.

lib/geometry.eigs

Computational geometry: 2D/3D points and vectors, line/segment intersection, triangles (area, centroid, circumcenter, incenter, barycentric coordinates), polygons (shoelace area, point-in-polygon, convexity), convex hull (Andrew's monotone chain), circles, 2D transforms, Hausdorff distance, solid geometry.

lib/lab.eigs

Experiment management and data collection framework composing EigenStore, observer semantics, stats, and experiment libraries. Record measurements with live observer feedback, detect stability, flag outliers, export to CSV.

Additional Libraries (0.9.0+)

lib/data.eigs

DataFrame operations on list-of-dicts: df_from_csv, df_select, df_where, df_sort_by, df_group_by, df_join, df_to_csv.

lib/stats.eigs

Statistical functions: mean, median, std_dev, variance, quantile, histogram, correlation, describe.

lib/concurrent.eigs

High-level concurrency: future, await_all, parallel_map, parallel_each, worker_pool.

lib/sync.eigs

Cooperative-task synchronization for the #408 task layer. A lock gives mutual exclusion across task_yield points — while one task holds it, another that tries to acquire cooperatively yields until it is released (correct because there is no preemption between the acquire check passing and the claim). lock_new, lock_acquire, lock_release, and with_lock of [lock, fn] (runs fn of null under the lock, releasing even if the body raises). Acquire only from within tasks — it spins with task_yield, so it needs the scheduler active.

lib/supervise.eigs

Observer-native supervision over the #408 task layer. Beyond BEAM-style crash-restart, it also detects the silently wedged worker — alive, not crashed, never timing out, but no longer making progress — by sampling each worker's progress trajectory and seeing it go stable (the EigenOS red-title pattern generalized). Workers publish raw progress with heartbeat of [slot, value]; the supervisor turns it into a bounded signature (dodging the #294 flat-entropy blind spot). supervisor_new, supervise of [sup, fn, slot], supervise_step, and supervise_run of [sup, max_ticks] (drive to settled); wedged and crashed workers are restarted from their spec under a per-worker restart-intensity cap. Eight slots. See examples/supervisor_tree.eigs.

lib/store.eigs

EigenStore high-level layer: find, find_one, upsert, bulk_put, to_dataframe.

lib/audio.eigs

Audio synthesis: play_note, note_freq, play_chord, drum sounds (play_kick, play_snare, play_hihat).

Uh oh!

FilesExpand file tree

STDLIB.md

Latest commit

History