Foundational schema aliases, runtime bindings, trait predicates, callable adapters, stack helpers, control combinators, and numeric utilities.

C runtime bindings

exit

(status --) Terminates the process with the Int32 status.

printf

(args format -- result) Writes formatted output through C printf and returns its Int32 result.
  • format is a Natx address of a zero-terminated C format string. args is one List or Tuple of variadic arguments in C argument order; use () when there are none.

write

(count buf fd -- writtenCount) Writes bytes from buf to file descriptor fd and returns the C result as Intx.
  • count is the requested byte count; count and buf have schema Natx, and fd has schema Int32.

Schema aliases and constants

Cond(-- cond)Pushes the default Cond value, FALSE.
Int8(-- int8)Pushes the default Int8 value, 0i8.
Int16(-- int16)Pushes the default Int16 value, 0i16.
Int32(-- int32)Pushes the default Int32 value, 0.
Int64(-- int64)Pushes the default Int64 value, 0i64.
Intx(-- intx)Pushes the default Intx value, 0ix.
Nat8(-- nat8)Pushes the default Nat8 value, 0n8.
Nat16(-- nat16)Pushes the default Nat16 value, 0n16.
Nat32(-- nat32)Pushes the default Nat32 value, 0n32.
Nat64(-- nat64)Pushes the default Nat64 value, 0n64.
Natx(-- natx)Pushes the default Natx value, 0nx.
Real32(-- real32)Pushes the default Real32 value, 0.0r32.
Real64(-- real64)Pushes the default Real64 value, 0.0.
Text(-- text)Pushes the empty Text value, "".
STDOUT_FILENO(-- fd)Pushes known Int32 value 1, the standard-output descriptor.
REF_SIZE(-- refSize)Pushes the size of a reference in bytes as a known Int32.

Remarks

Trait predicates

Contained objects, available value information, and valid lifetime methods affect capability results.

assignable?, copyable?, creatable?, and movable? test capability without validating a reference's address; TRUE can be returned for a NIL or unknown reference. initializable? tests initialization of the supplied object, so target/value information can change its result.

assignable?

(object -- cond) Reports whether the input supports assignment from an immutable source of the same dereferenced schema.
  • This is a compile-time capability test; no run-time assignment is performed.
  • A reference field does not by itself require an assignable target.

automatic?

(object -- cond) Returns TRUE for a Struct with a DIE field or a non-Ref field that recursively satisfies automatic?; returns FALSE otherwise.
  • Reads through an input reference, but does not follow Ref fields.
  • A DIE field is sufficient; otherwise a non-Ref field must recursively satisfy automatic?. Other objects return FALSE.

callable?

(object -- cond) Returns TRUE for a Block, a Code, or a Dict with a CALL field; returns FALSE otherwise.
  • Reads through a reference before testing the schema. The value, whether known or unknown, and NIL state do not change the result.

compilable?

(object -- cond) Returns TRUE when call accepts the object with the objects currently below it on the stack; returns FALSE otherwise.
  • Accepted: a Block or a known Text whose processing succeeds, and a Code or a Dict with CALL whose inputs are present on the stack. "1 2 +" compilable? is TRUE; "missingName" compilable? is FALSE; a Code with one Int32 input is FALSE on an empty stack and TRUE with an Int32 below it.
  • Unknown Text, a NIL Code and non-callable objects return FALSE. The test does not consume the objects below.

copyable?

(object -- cond) Reports whether copy construction from an immutable source is supported for the input's dereferenced schema and available value information.
  • This is a compile-time capability test; it does not copy the input.

creatable?

(object -- cond) Reports whether a new variable of the same dereferenced schema can be constructed.
  • This is a compile-time capability test; it does not construct the variable.

initializable?

(object -- cond) Reports whether manual initialization of the input object compiles.
  • This is a compile-time capability test; it does not initialize the object at run time.
  • NIL target information or a value-dependent INIT can change it.

int?

(object -- cond) Returns TRUE for schemas Int8, Int16, Int32, Int64, and Intx.
  • Reads through a reference; the numeric value does not matter.

movable?

(object -- cond) Reports whether a new object can be constructed by moving from the input; an immutable view returns FALSE.
  • This is a compile-time capability test; it does not move the object at run time.

nat?

(object -- cond) Returns TRUE for schemas Nat8, Nat16, Nat32, Nat64, and Natx.
  • Reads through a reference; the numeric value does not matter.

nil?

(object -- cond) Reports whether a non-Meta input is NIL.
  • NIL Ref, NIL Text, and NIL Code return TRUE; a live reference or an In-place scalar returns FALSE. The result may be unknown for a run-time reference.

number?

(object -- cond) Returns TRUE for signed integer, unsigned integer, or real schemas.
  • It is equivalent to the union of int?, nat?, and real?; Text, Cond, Block, Code, and Struct schemas return FALSE; a Ref is judged by its target schema.

real?

(object -- cond) Returns TRUE for Real32 and Real64 schemas.
  • Reads through a reference; the real value does not matter.

ref?

(object -- cond) Tests whether the input is a reference.

Remarks

  • When called, the Block receives non-Meta In-place inputs as references. Meta inputs return FALSE; Text and Code return TRUE.
  • Process ref? inline to distinguish an In-place stack object from a reference: 5 @ref? ucall returns FALSE, while an immutable or mutable scalar view returns TRUE.

sized?

(object -- cond) Returns TRUE for a Struct, Cond, numeric schema, or Block; returns FALSE for Text and Code. A Ref is judged by its target schema.
  • Reads through a reference. The result depends on schema kind, not value knownness.

tuple?

(object -- cond) Returns TRUE for a Struct schema whose fields are all unnamed.
  • Empty Tuple, List, and unnamed Tuple schemas return TRUE. A Dict with a named field returns FALSE.

virtualizable?

(object -- cond) Reports whether the schema admits a static object or reference representation.
  • Returns TRUE for every supported schema kind, including known and unknown values. TRUE does not mean that the current value can be stored in a static field; the field value must still be completely known.

Functional helpers and comparisons

failProc

(message --) Writes a failure message and any enabled call-trace details to standard output, then exits with status 2.
  • Without tracing, the output is the message followed by a line feed.
  • With -callTrace 1, PATH is the source path. With line-buffered output, each entry is in PATH at LINE:COLUMN followed by a line feed, and an additional line feed follows the trace. With fully buffered output, the at LINE:COLUMN lines follow the message, all path prefixes, and their trailing line feed.

pfunc

(pre call -- callable) Builds a callable Dict with public PRE and CALL fields.
  • PRE and CALL are public static fields. A known TRUE PRE selects the callable; known FALSE or a PRE that fails passes lookup to an older callable.

<

(left right -- cond) Calls right.less when present; otherwise calls left.greater when present with operands exchanged; otherwise uses the builtin comparison.

=

(left right -- cond) Calls right.equal when present; otherwise calls left.equal when present; otherwise uses the builtin comparison.

>

(left right -- cond) Calls right.greater when present; otherwise calls left.less when present with operands exchanged; otherwise uses the builtin comparison.

print

(text --) Writes Text bytes to standard output without adding a line feed.
  • Text need not be known. The call requests the Text byte count, including embedded NUL bytes, without adding a line feed or length value; the write result is discarded.

bind

(value body -- callable) Builds a callable Dict that supplies value before calling body.
  • The result has bindBody, bindValue, and CALL. For both stored values, an immutable view is copied when copyable?, and a mutable view is moved when movable?. Otherwise the original object or view is retained without a new object. A retained reference remains an alias, not an independent snapshot.
  • 5 [1 +] bind call yields 6.

compose

(body0 body1 -- callable) Builds a callable Dict that calls body0 and then body1.
  • The result has composeBody0, composeBody1, and CALL. For both stored values, an immutable view is copied when copyable?, and a mutable view is moved when movable?. Otherwise the original object or view is retained without a new object. A retained reference remains an alias, not an independent snapshot.
  • [1 +] [2 *] compose 5 swap call yields 12.

References and stack helpers

Ref

(object -- ref) Creates the NIL reference form for the input’s dereferenced schema, preserving the input view’s constness.
  • For a non-Meta In-place schema, the result is Ref or Cref to that schema. Text and Code retain their schema kinds. These forms are intended for signatures.

Cref

(object -- cref) Creates the immutable NIL reference form for the input’s dereferenced schema.
  • For a non-Meta In-place schema, the result is Cref. Text and Code retain their schema kinds.

reinterpret

(ref schemaObject -- view) Views ref’s storage using schemaObject’s dereferenced schema, without copying the stored value.
  • For an In-place target schema, the result is mutable only when both input views permit mutation. Text and Code retain their reference forms.
  • The caller must provide storage with the target layout, alignment, extent, and lifetime; reinterpret does not establish those conditions.

AsRef

(data -- callable) Wraps data in a Dict with public data and CALL fields.
  • Calling the wrapper calls data when it is callable; otherwise it reads data without calling it. A non-Meta In-place item is returned by reference, subject to the stored view and wrapper constness. Non-callable Meta and Text data keep their own form.
  • 5 AsRef call yields 5 Ref.

forceConst

(object -- result) Returns an immutable view of a non-Meta In-place object without copying its storage.
  • Meta, Text, and Code inputs keep their own form.

drop

(object --) Removes the top stack object.

dup

(object -- first second) Leaves two reads of the same object.
  • These operations introduce no implicit copy of an In-place value. A non-Meta In-place object is exposed through a reference that preserves its input view's constness. Meta objects remain Meta; Text and Code retain their own form.

swap

(a b -- bResult aResult) Leaves reads of the top two objects in reverse order.

over

(a b -- aResult bResult aResult) Leaves reads of a, b, and a in that order.

Control helpers and diagnostics

An executed inline position accepts a Block or known Text. The restriction applies only to positions that are processed; for example, 0 @exit times is a no-op. Branches selected by an unknown condition must leave compatible output counts and schemas, including reference schemas. A complete run-time loop iteration must restore the carried stack shape. Branches chosen by known conditions and compile-time iterations may change the carried stack shape.

when

(... cond body -- ...) Calls body when cond is TRUE; the supplied code determines the carried stack and additional results.
  • With a known condition, only the selected branch is processed. With an unknown condition, body must compile and leave outputs compatible with the skipped path. A Block body has a call boundary.

while

(... condition body -- ...) Repeats body while condition returns TRUE; the supplied code determines the carried stack and additional results.

times

(... count body -- ...) Calls body count times and exposes the Int32 ordinal i starting at zero.
  • body is processed inline. The common control rules apply.
  • Zero does not execute body, and a negative count is not an empty repetition.
  • Compile-time repetition is subject to -staticLoopLengthLimit; an unknown count permits run-time repetition.
  • 3 [i printStack _:;] times reports 0 Cref, 1 Cref, and 2 Cref.

ensure

(... predicate message -- ...) Calls predicate and fails when it returns FALSE; supplied code determines the carried stack and additional results.
  • A known FALSE uses the static-error path. A run-time FALSE passes the Text message to failProc and exits with status 2; the message may be unknown.
  • An unused message need not be known. Run-time branch and repetition shape rules apply to any carried stack.

assert

(... predicate message -- ...) Checks predicate when DEBUG is TRUE and rejects a known FALSE result in either mode.
  • With -ndebug, no run-time predicate evaluation is emitted: side effects and ordinary input consumption do not occur. A predicate that cannot compile is ignored; a compilable known FALSE still raises the supplied compile-time error.

&&

(cond callable -- cond) Returns FALSE without calling callable when cond is FALSE; otherwise returns callable's Cond.

||

(cond callable -- cond) Returns TRUE without calling callable when cond is TRUE; otherwise returns callable's Cond.

for

(... init condition iterate body -- ...) Runs init once, then condition, body, and iterate until condition is FALSE.
  • init, condition, and iterate are processed inline; body has a call boundary.
  • The common control rules apply. body accepts objects supported by call and runs across a call boundary.
  • init establishes initial state. A complete body/iterate cycle must satisfy the run-time stack-shape rule. Init-local visibility follows normal Block module rules.

sequence

(... callables -- ...) Calls guard item 0 before each step, then calls items 1 through the end in order while guard returns TRUE.
  • Every executed guard and step is processed inline.
  • The common control rules apply.
  • Supply a nonempty collection, including the guard item even when there are no steps.
  • A one-item collection does not execute its guard. Unknown-guard paths require compatible outputs, while known selection may change shape.

keep

(... object body -- ... saved) Calls body with a read of object, then leaves another read of object.
  • The body determines the number and schemas of its outputs; saved follows the shared view rule. 5 [1 +] keep yields 6 and 5 Ref.

touch

(objects count -- results) Reads the top count objects back onto the stack in their original order.

unwrap

(list -- fields) Reads the fields of list onto the stack in ordinal order.
  • In-place fields produce mutable references through a mutable list view and immutable references through an immutable list view. Meta, Text, and Code fields retain their own form.

wrap

(objects count -- collection) Collects reads of the top count objects into a List or Tuple.
  • Equal item schemas produce a List; differing schemas produce a Tuple; zero count produces the empty Tuple.
  • The shared view rule applies.

enum

(names type -- enumeration) Returns a Dict of static ordinal fields starting at zero, or the empty Tuple when names has no fields.
  • An empty Text name creates an unnamed field; it does not remove the field. Duplicate lookup selects the last field. A generated field's ordinal is cast to the numeric schema supplied by type.

Numeric helpers

iterate

(bound ordinalRef -- cond) Increments ordinal and returns TRUE while the new ordinal is below bound.
  • iterate increments before testing; a plain object is consumed and its update is lost.
  • Use i: 0; [10 @i iterate] [ ... ] while; this visits 1 through 9. Start at -1 to visit 0 through 9.

riterate

(bound ordinalRef -- cond) Returns TRUE while ordinal is above bound, then decrements ordinal.
  • riterate tests before decrementing and decrements even when it returns FALSE; a plain object is consumed and its update is lost.
  • Use i: 10; [0 @i riterate] [ ... ] while; this visits 9 through 0 and leaves i at -1.

abs

(value -- value) Returns the absolute value with the input numeric schema.
  • A signed minimum is negated without a special case, so it remains the signed minimum when the numeric representation overflows. For real inputs, negative zero is preserved and NaN returns NaN.

sign

(value -- sign) Returns Int32 1 for positive, -1 for negative, and 0 for zero.
  • NaN also returns 0.

sqr

(value -- value) Multiplies value by itself and keeps the multiplication result schema.

max

(a b -- value) Returns a when b is less than a; otherwise returns b.
  • For non-Meta In-place inputs, the result is an immutable view of the selected input, not a copy.

min

(a b -- value) Returns a when a is less than b; otherwise returns b.
  • For non-Meta In-place inputs, the result is an immutable view of the selected input, not a copy.

clamp

(value lower upper -- value) Returns lower below the lower endpoint, upper above the upper endpoint, and value otherwise.
  • Both endpoints are inclusive. No implicit numeric conversion is performed.
  • For non-Meta In-place inputs, the result is a view of the selected input with that input’s constness. Unknown comparisons require all possible result views to have compatible schemas and mutability. Use @v 0 10 clamp for mutable results, or immutable views of all three inputs for an immutable result.

between

(value lower upper -- cond) Returns TRUE when value is not less than lower and upper is not less than value.
  • For ordered non-NaN inputs this is the inclusive interval. A NaN value can pass between with ordinary endpoints.

within

(value lower upper -- cond) Returns TRUE when value is not less than lower and value is less than upper.
  • For ordered non-NaN inputs this is the half-open interval. A NaN lower endpoint can admit a value below the upper endpoint.

Collection helpers

!

(source key collection --) When collection has at, writes source through the destination returned for key; otherwise the builtin ordinal operation applies.

@

(key collection -- item) When collection has at, returns whatever it returns for key; otherwise the builtin ordinal operation applies.
  • The key and result type are determined by at.

isBuiltinTuple

(object -- cond) Returns TRUE for a Struct schema that is empty Tuple or has an unnamed first field.
  • It does not require every field to be unnamed. A named first field returns FALSE.

hasSchemaName

(object name -- cond) Returns TRUE when object has a SCHEMA_NAME field whose value equals name.
  • The comparison uses =; the field need not be static. A static Text SCHEMA_NAME is the conventional schema-name form.

Examples

Numeric helpers

"control" use

{} () {} [
  3 5 max printStack _:;
  3 5 min printStack _:;
  5 0 10 within printStack _:;
] "main" exportFunction

Expected Output During Compilation

5 Cref
3 Cref
TRUE

times

"control" use

{} () {} [
  3 [i printStack _:;] times
] "main" exportFunction

Expected Output During Compilation

0 Cref
1 Cref
2 Cref

Runtime example

"String"  use
"control" use

{} Int32 {} [
  ("max=" 3 5 max LF
    "min=" 3 5 min LF
    "within=" 5 0 10 within LF) printList
  0
] "main" exportFunction

Expected Output

max=5
min=3
within=TRUE

See also