Rye Function Reference: Base ( Updated: "2026-11-02" )

true

Returns a boolean true value.

no arguments

returns boolean true value

true
; returns true

true |type?
; returns boolean

false

Returns a boolean false value.

no arguments

returns boolean false value

false
; returns false

false |type?
; returns boolean

not

Performs logical negation on boolean values only.

Args: 1

Types: 1 [ Boolean ]

value Boolean value to be negated

returns boolean false if the input is true, true if the input is false

not true
; returns false

not false
; returns true

not 0
; correctly causes error:
; `not` expected Boolean for argument 1 

not 5
; correctly causes error:
; `not` expected Boolean for argument 1 

and

Performs a logical AND operation between two boolean values, or an element-wise bitwise AND operation between two equal-length bytes values.

Args: 2

Types: 1 [ Boolean Bytes ] 2 [ Boolean Bytes ]

value1 First value (boolean or bytes)

value2 Second value (boolean or bytes)

returns boolean result of logical AND if both inputs are booleans, or element-wise bitwise AND of two equal-length bytes values

true .and true
; returns true

false .and true
; returns false

true .and false
; returns false

false .and false
; returns false

bytes { 255 240 } |and bytes { 240 15 } |first
; returns 240

bytes { 255 240 } |and bytes { 240 15 } |last
; returns 0

bytes { 255 } |and bytes { 240 15 }
; correctly causes error:
; `and`: Bytes values must have equal length for bitwise AND. 

true .and 5
; correctly causes error:
; `and` expected Boolean for argument 2 

5 .and true
; correctly causes error:
; `and` expected Boolean, Bytes for argument 1 

"string" .and true
; correctly causes error:
; `and` expected Boolean, Bytes for argument 1 

or

Performs a logical OR operation between two boolean values, or an element-wise bitwise OR operation between two equal-length bytes values.

Args: 2

Types: 1 [ Boolean Bytes ] 2 [ Boolean Bytes ]

value1 First value (boolean or bytes)

value2 Second value (boolean or bytes)

returns boolean result of logical OR if both inputs are booleans, or element-wise bitwise OR of two equal-length bytes values

true .or true
; returns true

false .or true
; returns true

true .or false
; returns true

false .or false
; returns false

bytes { 255 240 } |or bytes { 240 15 } |first
; returns 255

bytes { 255 240 } |or bytes { 240 15 } |last
; returns 255

bytes { 255 } |or bytes { 240 15 }
; correctly causes error:
; `or`: Bytes values must have equal length for bitwise OR. 

true .or 5
; correctly causes error:
; `or` expected Boolean for argument 2 

5 .or true
; correctly causes error:
; `or` expected Boolean, Bytes for argument 1 

"string" .or true
; correctly causes error:
; `or` expected Boolean, Bytes for argument 1 

xor

Performs a logical XOR (exclusive OR) operation between two boolean values, or an element-wise bitwise XOR operation between two equal-length bytes values.

Args: 2

Types: 1 [ Boolean Bytes ] 2 [ Boolean Bytes ]

value1 First value (boolean or bytes)

value2 Second value (boolean or bytes)

returns boolean result of logical XOR if both inputs are booleans, or element-wise bitwise XOR of two equal-length bytes values

true .xor true
; returns false

false .xor true
; returns true

true .xor false
; returns true

false .xor false
; returns false

bytes { 255 240 } |xor bytes { 240 15 } |first
; returns 15

bytes { 255 240 } |xor bytes { 240 15 } |last
; returns 255

bytes { 255 } |xor bytes { 240 15 }
; correctly causes error:
; `xor`: Bytes values must have equal length for bitwise XOR. 

true .xor 5
; correctly causes error:
; `xor` expected Boolean for argument 2 

5 .xor true
; correctly causes error:
; `xor` expected Boolean, Bytes for argument 1 

"string" .xor true
; correctly causes error:
; `xor` expected Boolean, Bytes for argument 1 

all

Evaluates all expressions in a block and returns the last value if all are truthy, or the first falsy value encountered.

Args: 1

Types: 1 [ Block ]

block Block of expressions to evaluate

returns the last value if all expressions are truthy, otherwise the first falsy value encountered

all { 1 2 3 }
; returns 3

all { 1 0 3 }
; returns 3

all { 1 false 3 }
; returns false

all { true true true }
; returns true

all "not-a-block"
; correctly causes error:
; `all` expected Block for argument 1 

any

Evaluates expressions in a block until a truthy value is found and returns it, or returns the last value if none are truthy.

Args: 1

Types: 1 [ Block ]

block Block of expressions to evaluate

returns the first truthy value encountered, or the last value if none are truthy

any { 1 2 3 }
; returns 1

any { 0 1 3 }
; returns 0

any { false false 3 }
; returns 3

any { false false false }
; returns false

any "not-a-block"
; correctly causes error:
; `any` expected Block for argument 1 

any\with

Evaluates expressions in a block with the provided value injected, returning the first truthy result or the last result if none are truthy. Commas between expressions are supported.

Args: 2

Types: 2 [ Block ]

value Value to be used as input to each expression in the block

block Block of expressions to evaluate with the provided value injected

returns the first truthy result of applying an expression to the value, or the last result if none are truthy

any\with 10 { + 10 , * 10 }
; returns 20

any\with 0 { + 10 , * 10 }
; returns 10

any\with 5 { - 10 , + 10 }
; returns -5

any\with false { .not , .string }
; returns true

any\with "abc" { .length? , .string }
; returns 3

any\with 5 "not-a-block"
; correctly causes error:
; `any\with` expected Block for argument 2 

inc

Increments an integer value by 1.

Args: 1

Types: 1 [ Integer ]

value Integer to increment

returns integer value incremented by 1

inc 123
; returns 124

inc 0
; returns 1

inc -5
; returns -4

inc "123"
; correctly causes error:
; `inc` expected Integer for argument 1 

dec

Decrements an integer value by 1.

Args: 1

Types: 1 [ Integer ]

value Integer to decrement

returns integer value decremented by 1

dec 124
; returns 123

dec 1
; returns 0

dec -4
; returns -5

dec "123"
; correctly causes error:
; `dec` expected Integer for argument 1 

negate

Negates a number by multiplying it by -1, works with integers, decimals, and complex numbers.

Args: 1

Types: 1 [ Integer Decimal Complex ]

value Number (integer, decimal, or complex) to negate

returns negated number of the same type

negate 123
; returns -123

negate -123
; returns 123

negate 0
; returns 0

negate 5.5
; returns -5.5

negate -2.3
; returns 2.3

negate "123"
; correctly causes error:
; `negate` expected Integer, Decimal, Complex for argument 1 

invert

Calculates the reciprocal (1/x) of a number, works with integers, decimals, and complex numbers.

Args: 1

Types: 1 [ Integer Decimal Complex ]

value Number (integer, decimal, or complex) to invert (must not be zero)

returns reciprocal (1/value) as decimal or complex number

invert 2
; returns 0.5

invert 4
; returns 0.25

invert 0.5
; returns 2

invert -2
; returns -0.5

invert 1
; returns 1

invert 0
; correctly causes error:
; `invert`: Can't invert zero. 

invert "123"
; correctly causes error:
; `invert` expected Integer, Decimal, Complex for argument 1 

is-positive

Checks if a number is positive (greater than zero).

Args: 1

Types: 1 [ Integer Decimal ]

value Integer or decimal to check

returns boolean true if the value is positive, false otherwise

is-positive 123
; returns true

is-positive -123
; returns false

is-positive 0
; returns false

is-positive 5.5
; returns true

is-positive "123"
; correctly causes error:
; `is-positive` expected Integer, Decimal for argument 1 

sign

Returns the sign of a number as -1, 0, or 1.

Args: 1

Types: 1 [ Integer Decimal ]

value Integer or decimal to check

returns integer sign of the value (-1 for negative, 0 for zero, 1 for positive)

sign 123
; returns 1

sign -123
; returns -1

sign 0
; returns 0

sign 5.5
; returns 1

sign -0.5
; returns -1

sign "123"
; correctly causes error:
; `sign` expected Integer, Decimal for argument 1 

is-zero

Checks if a number is exactly zero.

Args: 1

Types: 1 [ Integer Decimal ]

value Integer or decimal to check

returns boolean true if the value is zero, false otherwise

is-zero 0
; returns true

is-zero 123
; returns false

is-zero 0
; returns true

is-zero "123"
; correctly causes error:
; `is-zero` expected Integer, Decimal for argument 1 

is-multiple-of

Checks if the first integer is evenly divisible by the second integer.

Args: 2

Types: 1 [ Integer ] 2 [ Integer ]

value Integer to check

divisor Integer divisor to check against

returns boolean true if value is divisible by divisor with no remainder, false otherwise

10 .is-multiple-of 2
; returns true

10 .is-multiple-of 3
; returns false

15 .is-multiple-of 5
; returns true

0 .is-multiple-of 5
; returns true

is-odd

Checks if an integer is odd (not divisible by 2).

Args: 1

Types: 1 [ Integer ]

value Integer to check

returns boolean true if the value is odd, false if even

3 .is-odd
; returns true

2 .is-odd
; returns false

0 .is-odd
; returns false

-5 .is-odd
; returns true

is-even

Checks if an integer is even (divisible by 2).

Args: 1

Types: 1 [ Integer ]

value Integer to check

returns boolean true if the value is even, false if odd

3 .is-even
; returns false

2 .is-even
; returns true

0 .is-even
; returns true

-4 .is-even
; returns true

mod

Calculates the modulo (remainder) when dividing the first integer by the second.

Args: 2

Types: 1 [ Integer ] 2 [ Integer ]

value Integer dividend

divisor Integer divisor

returns integer remainder after division

4 .mod 2
; returns 0

5 .mod 2
; returns 1

5 .mod 3
; returns 2

-5 .mod 3
; returns -2

4 .mod 0
; correctly causes error:
; `mod`: Can't divide by Zero. 

random\integer

Generates a cryptographically secure random integer between 0 (inclusive) and the specified maximum (exclusive).

Args: 1

Types: 1 [ Integer ]

max Upper bound (exclusive) for the random number

returns random integer in the range [0, max)

random\integer 2 |type?
; returns integer

random\integer 1 |< 2
; returns true

random\integer 100 || >= 0
; returns true

random\decimal

Generates a cryptographically secure random decimal between 0.0 (inclusive) and the specified maximum (exclusive).

Args: 1

Types: 1 [ Decimal Integer ]

max Upper bound (exclusive) for the random number

returns random decimal in the range [0.0, max)

random\decimal 2 |type?
; returns decimal

random\decimal 1 |< 1
; returns true

random\decimal 100 || >= 0
; returns true

inc!

Increments an integer value stored in a variable (word) by 1 and updates the variable in-place.

Args: 1

Types: 1 [ Word ]

word Word referring to an integer value to increment

returns the new incremented integer value

a:: 123 inc! 'a a
; returns 124

counter:: 0 inc! 'counter counter
; returns 1

inc! 123
; correctly causes error:
; `inc!` expected Word for argument 1 

dec!

Decrements an integer value stored in a variable (word) by 1 and updates the variable in-place.

Args: 1

Types: 1 [ Word ]

word Word referring to an integer value to decrement

returns the new decremented integer value

a:: 123 dec! 'a a
; returns 122

counter:: 1 dec! 'counter counter
; returns 0

dec! 123
; correctly causes error:
; `decr!` expected Word for argument 1 

_.

Discards the input value and returns a void value, useful only for Eyr (stack based dialect).

Args: 1

value Any value to discard

returns void value (used to discard values)

4 . .type?
; returns void

"hello" . .type?
; returns void

_+

Adds two numerical values. Accepts Integer, Decimal, Complex, Time and Vector.

Args: 2

Types: 1 [ Integer Decimal Complex Time Vector Matrix ] 2 [ Integer Decimal Complex Vector Matrix ]

value1 First value (integer, decimal, complex, time, vector)

value2 Second value to add (integer, decimal, complex, duration, vector)

returns result of adding values, type depends on input types

1 + 1
; returns 2

3 + 4
; returns 7

5.6 + 7.8
; returns 13.399999999999999

2 + 3.5
; returns 5.5

vector [ 1 2 3 ] |+ vector [ 4 5 6 ] |block
; returns { 5 7 9 }

_-

Subtracts the second number from the first, working with integers, decimals, complex numbers, and vectors.

Args: 2

Types: 1 [ Integer Decimal Complex Time Vector Matrix ] 2 [ Integer Decimal Complex Time Vector Matrix ]

value1 First number (integer, decimal, or vector)

value2 Second number to subtract from the first

returns result of subtracting value2 from value1

2 - 1
; returns 1

5 - 6
; returns -1

5.5 - 2.2
; returns 3.3

5 - 2.5
; returns 2.5

vector [ 5 7 9 ] |- vector [ 4 5 6 ] |block
; returns { 1 2 3 }

_*

Multiplies two numbers, working with integers, decimals, complex numbers, and vectors (scalar multiplication).

Args: 2

Types: 1 [ Integer Decimal Complex Vector Matrix ] 2 [ Integer Decimal Complex Vector Matrix ]

value1 First number (integer, decimal, or vector)

value2 Second number to multiply by (scalar for vectors)

returns product of the two numbers, or scaled vector

4 * 2
; returns 8

2.5 * -2
; returns -5

0 * 5
; returns 0

1.5 * 2.5
; returns 3.75

vector [ 1 2 3 ] |* 2 |block
; returns { 2 4 6 }

vector [ 10 20 ] |* 0.5 |block
; returns { 5 10 }

_/

Divides the first number by the second and returns a result, with error checking for division by zero.

Args: 2

Types: 1 [ Integer Decimal Complex ] 2 [ Integer Decimal Complex ]

value1 Dividend (integer or decimal)

value2 Divisor (integer or decimal, must not be zero)

returns decimal result of dividing value1 by value2

4 / 2
; returns 2

102 / 2
; returns 51

5 / 2
; returns 2.5

5 / 0
; correctly causes error:
; `_/`: Can't divide by Zero. 

_//

Performs integer division, dividing the first number by the second and truncating to an integer result.

Args: 2

Types: 1 [ Integer Decimal ] 2 [ Integer Decimal ]

value1 Dividend (integer or decimal)

value2 Divisor (integer or decimal, must not be zero)

returns integer result of dividing value1 by value2 (truncated)

5 // 2
; returns 2

102 // 5
; returns 20

7.99 // 2
; returns 3

-5 // 2
; returns -2

5 // 0
; correctly causes error:
; `_//`: Can't divide by Zero. 

_%

Alias for mod - calculates the modulo (remainder) when dividing the first integer by the second.

Args: 2

Types: 1 [ Integer ] 2 [ Integer ]

value Integer dividend

divisor Integer divisor

returns integer remainder after division

4 % 2
; returns 0

5 % 2
; returns 1

5 % 3
; returns 2

4 % 0
; correctly causes error:
; `_%`: Can't divide by Zero. 

clamp

Clamps a number between a minimum and maximum value, ensuring the result stays within the specified bounds.

Args: 3

Types: 1 [ Integer Decimal ] 2 [ Integer Decimal ] 3 [ Integer Decimal ]

value Number (integer or decimal) to clamp

min Minimum value (integer or decimal)

max Maximum value (integer or decimal)

returns clamped number, ensuring value is between min and max (inclusive)

clamp 5 0 10
; returns 5

clamp -5 0 10
; returns 0

clamp 15 0 10
; returns 10

clamp 5.5 0 10
; returns 5.5

clamp -2.3 0 10
; returns 0

clamp 12.7 0 10
; returns 10

clamp "5" 0 10
; correctly causes error:
; `clamp` expected Integer, Decimal for argument 1 

_=

Compares two values for equality, returning 1 if equal or 0 if not equal.

Args: 2

value1 First value to compare

value2 Second value to compare

returns boolean true if values are equal, false otherwise

5 = 5
; returns true

5 = 4
; returns false

"abc" = "abc"
; returns true

{ 1 2 } = { 1 2 }
; returns true

{ 1 2 } = { 2 1 }
; returns false

_!=

Compares two values for inequality, returning true if not equal or false if equal.

Args: 2

value1 First value to compare

value2 Second value to compare

returns boolean true if values are not equal, false otherwise

5 != 5
; returns false

5 != 4
; returns true

"abc" != "abc"
; returns false

"abc" != "def"
; returns true

{ 1 2 } != { 1 2 }
; returns false

{ 1 2 } != { 2 1 }
; returns true

_>

Compares if the first value is greater than the second value.

Args: 2

value1 First value to compare

value2 Second value to compare

returns boolean true if value1 is greater than value2, false otherwise

6 > 5
; returns true

5 > 5
; returns false

4 > 5
; returns false

5.5 > 5
; returns true

"b" > "a"
; returns true

_>=

Compares if the first value is greater than or equal to the second value.

Args: 2

value1 First value to compare

value2 Second value to compare

returns boolean true if value1 is greater than or equal to value2, false otherwise

5 >= 6
; returns false

5 >= 5
; returns true

6 >= 5
; returns true

4 >= 5
; returns false

"b" >= "a"
; returns true

"a" >= "a"
; returns true

_<

Compares if the first value is less than the second value.

Args: 2

value1 First value to compare

value2 Second value to compare

returns boolean true if value1 is less than value2, false otherwise

5 < 6
; returns true

5 < 5
; returns false

6 < 5
; returns false

4.5 < 5
; returns true

"a" < "b"
; returns true

_<=

Compares if the first value is less than or equal to the second value.

Args: 2

value1 First value to compare

value2 Second value to compare

returns boolean true if value1 is less than or equal to value2, false otherwise

5 <= 6
; returns true

5 <= 5
; returns true

6 <= 5
; returns false

4.5 <= 5
; returns true

"a" <= "b"
; returns true

"a" <= "a"
; returns true

newline

Returns a string containing a single newline character.

no arguments

returns a string containing a single newline character

newline
; returns "
; "

tab

Returns a string containing a single tab character.

no arguments

returns a string containing a single tab character

tab
; returns "	"

ln

Appends a newline character to the end of a string.

Args: 1

string String to append a newline to

returns a new string with a newline character appended

"123" .ln
; returns "123
; "

"hello" .ln
; returns "hello
; "

trim

Removes all leading and trailing whitespace characters from a string.

Args: 1

Types: 1 [ String ]

string String to trim

returns a new string with leading and trailing whitespace removed

trim " ASDF "
; returns "ASDF"

trim "   ASDF   "
; returns "ASDF"

trim "	
ASDF
"
; returns "ASDF"

trim\

Removes all leading and trailing occurrences of the specified characters from a string.

Args: 2

Types: 1 [ String ] 2 [ String ]

string String to trim

cutset String containing the characters to trim

returns a new string with specified characters removed from both ends

trim\ "__ASDF__" "_"
; returns "ASDF"

trim\ "##Hello##" "#"
; returns "Hello"

trim\right

Removes all trailing occurrences of the specified characters from a string.

Args: 2

Types: 1 [ String ] 2 [ String ]

string String to trim

cutset String containing the characters to trim

returns a new string with specified characters removed from the right end

trim\right "__ASDF__" "_"
; returns "__ASDF"

trim\right "  ASDF  " " "
; returns "  ASDF"

trim\right "Hello!!!" "!"
; returns "Hello"

trim\left

Removes all leading occurrences of the specified characters from a string.

Args: 2

Types: 1 [ String ] 2 [ String ]

string String to trim

cutset String containing the characters to trim

returns a new string with specified characters removed from the left end

trim\left "___ASDF__" "_"
; returns "ASDF__"

trim\left "  ASDF  " " "
; returns "ASDF  "

trim\left "###Hello" "#"
; returns "Hello"

replace

Replaces all occurrences of a substring with another string.

Args: 3

Types: 1 [ String ] 2 [ String ] 3 [ String ]

string Original string

old Substring to replace

new Replacement string

returns a new string with all occurrences of old replaced by new

replace "...xo..." "xo" "LoL"
; returns "...LoL..."

replace "...xoxo..." "xo" "LoL"
; returns "...LoLLoL..."

replace "hello world" "world" "everyone"
; returns "hello everyone"

replace "remove--dashes" "-" ""
; returns "removedashes"

substring

Extracts a portion of a string or secret between zero-based character positions (start inclusive, end exclusive).

Args: 3

Types: 1 [ String ] 2 [ Integer ] 3 [ Integer ]

string String to extract from

start Starting position (0-based, inclusive)

end Ending position (0-based, exclusive)

returns a new string containing the specified substring

substring "xoxo..." 0 4
; returns "xoxo"

substring "...xoxo..." 3 7
; returns "xoxo"

substring "hello world" 6 11
; returns "world"

contains

Checks if a string, block or list contains a specific value, returning true if found or false if not found.

Args: 2

Types: 1 [ String Block List ] 2 [ String Integer ]

collection String, block or list to search in

value Value to search for

returns true if the collection contains the value, false otherwise

contains "...xoxo..." "xo"
; returns true

contains "...xoxo..." "lol"
; returns false

contains { ".." "xoxo" ".." } "xoxo"
; returns true

contains { ".." "xoxo" ".." } "lol"
; returns false

contains list { 1 2 3 } 2
; returns true

contains\flag

Checks if a block contains a specific flag (long or short), returning true if found or false if not found.

Args: 2

Types: 1 [ Block ] 2 [ Flagword ]

collection block of flagwords or flag strings to search in

value Flag value to search for

returns true if the collection contains the flag in short or long form, false otherwise

contains\flag { --help --yello -h } -h/--help
; returns true

contains\flag load "hello --help ho" -h/--help
; returns true

contains\flag { hello yello --ho } -h/--help
; returns false

contains\flag { --hello yello ho } -h/--help
; returns false

has-suffix

Checks if a string ends with a specific suffix, returning true if it does or false if it doesn't.

Args: 2

Types: 1 [ String ] 2 [ String ]

string String to check

suffix Suffix to look for

returns true if the string ends with the suffix, false otherwise

has-suffix "xoxo..." "xoxo"
; returns false

has-suffix "...xoxo" "xoxo"
; returns true

has-suffix "hello.txt" ".txt"
; returns true

has-prefix

Checks if a string starts with a specific prefix, returning true if it does or false if it doesn't.

Args: 2

Types: 1 [ String ] 2 [ String ]

string String to check

prefix Prefix to look for

returns true if the string starts with the prefix, false otherwise

has-prefix "xoxo..." "xoxo"
; returns true

has-prefix "...xoxo" "xoxo"
; returns false

has-prefix "http://example.com" "http://"
; returns true

index?

Finds the 0-based index of the first occurrence of a value in a string or block.

Args: 2

Types: 1 [ Block String ] 2 [ String ]

collection String or block to search in

value Value to search for

returns integer index (0-based) of the first occurrence of the value, or -1 if not found

index? "...xo..." "xo"
; returns 3

index? "xo..." "xo"
; returns 0

index? { "xo" ".." } "xo"
; returns 0

index? { ".." "xo" ".." } "xo"
; returns 1

position?

Finds the 1-based position of the first occurrence of a value in a string or block.

Args: 2

Types: 1 [ String Block ] 2 [ String ]

collection String or block to search in

value Value to search for

returns integer position (1-based) of the first occurrence of the value, or error if not found

position? "...xo..." "xo"
; returns 4

position? "xo..." "xo"
; returns 1

position? { "xo" ".." } "xo"
; returns 1

position? { ".." "xo" ".." } "xo"
; returns 2

encode-to\base64

Encodes a string or binary data as a base64 string.

Args: 1

Types: 1 [ String Native Bytes ]

data String or native bytes/pem-block to encode

returns base64-encoded string

encode-to\base64 "abcd"
; returns "YWJjZA=="

encode-to\base64 "hello world"
; returns "aGVsbG8gd29ybGQ="

decode\base64

Decodes a base64-encoded string back to its original form.

Args: 1

Types: 1 [ String ]

string Base64-encoded string to decode

returns decoded string

decode\base64 encode-to\base64 "abcd"
; returns "abcd"

decode\base64 "aGVsbG8gd29ybGQ="
; returns "hello world"

encode-to\hex

Encodes a string or bytes value as a hexadecimal string.

Args: 1

Types: 1 [ String Bytes ]

data String or bytes native value to encode

returns hexadecimal-encoded string

encode-to\hex "abcd"
; returns "61626364"

encode-to\hex decode\hex "48656c6c6f20776f726c64"
; returns "48656c6c6f20776f726c64"

decode\hex

Decodes a hexadecimal string to a bytes native value.

Args: 1

Types: 1 [ String ]

string hexadecimal-encoded string to decode

returns bytes native value containing the decoded data

decode\hex "48656c6c6f20576f726c64" |type?
; returns bytes

decode\hex "48656c6c6f20576f726c64" |encode-to\hex
; returns "48656c6c6f20576f726c64"

decode\hex "invalid"
; correctly causes error:
; `decode\hex`: Failure to decode string. 

space

Appends a space character to the end of a string.

Args: 1

Types: 1 [ String ]

string String to append a space to

returns a new string with a space character appended

"abcd" .space
; returns "abcd "

"" .space
; returns " "

capitalize

Converts the first character of a string to uppercase, leaving the rest unchanged.

Args: 1

Types: 1 [ String ]

string String to capitalize

returns a new string with the first character converted to uppercase

capitalize "abcde"
; returns "Abcde"

capitalize "hello world"
; returns "Hello World"

capitalize "HELLO"
; returns "Hello"

lower

Converts all characters in a string to lowercase.

Args: 1

Types: 1 [ String ]

string String to convert

returns a new string with all characters converted to lowercase

lower "ABCDE"
; returns "abcde"

lower "Hello World"
; returns "hello world"

lower "123ABC"
; returns "123abc"

upper

Converts all characters in a string to uppercase.

Args: 1

Types: 1 [ String ]

string String to convert

returns a new string with all characters converted to uppercase

upper "abcde"
; returns "ABCDE"

upper "Hello World"
; returns "HELLO WORLD"

upper "123abc"
; returns "123ABC"

concat3

Concatenates three strings together into a single string.

Args: 3

Types: 1 [ String ] 2 [ String ] 3 [ String ]

string1 First string

string2 Second string

string3 Third string

returns a new string containing all three strings concatenated together

concat3 "aa" "BB" "cc"
; returns "aaBBcc"

concat3 "hello" " " "world"
; returns "hello world"

join

Concatenates all strings, numbers (integers and decimals) or URIs in a block or list into a single string with no separator. If the first element is a URI, returns a URI.

Args: 1

Types: 1 [ List Block ]

collection Block or list of strings, numbers (integers and decimals) or URIs to join

returns a single string with all values concatenated together, or a URI if first element is a URI

join { "Mary" "Anne" }
; returns "MaryAnne"

join { "Spot" "Fido" "Rex" }
; returns "SpotFidoRex"

join { 1 2 3 }
; returns "123"

join { 1.5 2.25 3 }
; returns "1.5000002.2500003.000000"

join { https://example.com/ "path" } |type?
; returns uri

join { }
; returns ""

join\with

Concatenates all strings, integers or decimals in a block or list into a single string with a specified delimiter between values.

Args: 2

Types: 1 [ List Block ] 2 [ String ]

collection Block or list of strings, integers or decimals to join

delimiter String to insert between each value

returns a single string with all values concatenated with the delimiter between them

join\with { "Mary" "Anne" } " "
; returns "Mary Anne"

join\with { "Spot" "Fido" "Rex" } "/"
; returns "Spot/Fido/Rex"

join\with { 1 2 3 } "-"
; returns "1-2-3"

join\with { 1.5 2.25 3 } "-"
; returns "1.500000-2.250000-3.000000"

split

Splits a string into a block of strings using a separator string.

Args: 2

Types: 1 [ String ] 2 [ String ]

string String to split

separator String that separates values

returns a block of strings resulting from splitting the input string

split "a,b,c" ","
; returns { "a" "b" "c" }

split "hello world" " "
; returns { "hello" "world" }

split "one::two::three" "::"
; returns { "one" "two" "three" }

split "no-separator" ","
; returns { "no-separator" }

split\quoted

Splits a string into a block of strings using a separator, while respecting quoted sections that should remain intact.

Args: 3

Types: 1 [ String ] 2 [ String ] 3 [ String ]

string String to split

separator String that separates values

quote String that marks quoted sections that should not be split

returns a block of strings resulting from splitting the input string, preserving quoted sections

split\quoted "`a,b`,c,d" "," "`"
; returns { "`a,b`" "c" "d" }

split\quoted "'hello, world',foo,bar" "," "'"
; returns { "'hello, world'" "foo" "bar" }

split\many

Splits a string into a block of strings using any character in the separators string as a delimiter.

Args: 2

Types: 1 [ String ] 2 [ String ]

string String to split

separators String containing all characters that should be treated as separators

returns a block of strings resulting from splitting the input string at any of the separator characters

split\many "192.0.0.1" "."
; returns { "192" "0" "0" "1" }

split\many "abcd..e.q|bar" ".|"
; returns { "abcd" "e" "q" "bar" }

split\many "a;b,c:d" ";,:"
; returns { "a" "b" "c" "d" }

split\every

Splits a string or block into chunks of the specified size, with any remaining elements in the last chunk.

Args: 2

Types: 1 [ String Block ] 2 [ Integer ]

collection String or block to split

size Number of elements in each chunk

returns a block of strings or blocks, each containing at most 'size' elements

split\every "abcdefg" 3
; returns { "abc" "def" "g" }

split\every "abcdefg" 2
; returns { "ab" "cd" "ef" "g" }

split\every "abcdef" 2
; returns { "ab" "cd" "ef" }

split\every { 1 2 3 4 5 } 2
; returns { { 1 2 } { 3 4 } { 5 } }

url-encode

Encodes a block of name: value pairs as a URL query string (e.g. name=John+Doe&city=New+York), percent-encoding all special characters. Keys can be set-words (name:) or strings ("name"), values can be strings, integers, decimals, or words (looked up in context).

Args: 1

Types: 1 [ Block ]

params Block of name

returns URL query string with pairs joined with '&', all special characters percent-encoded (no leading '?')

url-encode { name: "John Doe" city: "New York" } |contains "city=New+York"
; returns true

url-encode { }
; returns ""

url-encode { q: "hello world" }
; returns "q=hello+world"

url-encode { a: "foo" b: "bar" } |contains "a=foo"
; returns true

url-encode { a: "foo" b: "bar" } |contains "b=bar"
; returns true

url-encode { "my-key" "val" } |contains "my-key=val"
; returns true

x: "hello" url-encode { q: x }
; returns "q=hello"

url-encode "not-a-block"
; correctly causes error:
; `url-encode` expected Block for argument 1 

unix-micro?

Converts a time object to Unix time in microseconds (microseconds since January 1, 1970 UTC).

Args: 1

Types: 1 [ Time ]

time Time object to convert

returns integer representing Unix time in microseconds

now |unix-micro? |type?
; returns integer

unix-milli?

Converts a time object to Unix time in milliseconds (milliseconds since January 1, 1970 UTC).

Args: 1

Types: 1 [ Time ]

time Time object to convert

returns integer representing Unix time in milliseconds

now |unix-milli? |type?
; returns integer

weekday?

Extracts the day of the week from a time object as an integer (0=Sunday through 6=Saturday).

Args: 1

Types: 1 [ Time ]

time Time object to extract weekday from

returns integer representing day of week (0=Sunday, 1=Monday, ..., 6=Saturday)

date "2023-01-01" |weekday?
; returns 0

date

Creates a time object from a date string in YYYY-MM-DD format.

Args: 1

Types: 1 [ String ]

datestr String in "YYYY-MM-DD" format

returns time object representing the specified date

date "2023-01-15" |type?
; returns time

date "2023-01-15" |day?
; returns 15

date "2023-06-20" |month?
; returns 6

datetime

Creates a time object from a datetime string in YYYY-MM-DDThh:mm:ss format.

Args: 1

Types: 1 [ String ]

datetimestr String in "YYYY-MM-DDThh

returns time object representing the specified date and time

datetime "2023-01-15T14:30:45" |type?
; returns time

datetime "2023-01-15T14:30:45" |hour?
; returns 14

now

Creates a time object representing the current local time.

no arguments

returns time object representing the current time

now |type?
; returns time

yearday?

Extracts the day of year from a time object as an integer (1-366).

Args: 1

Types: 1 [ Time ]

time Time object to extract day of year from

returns integer representing day of year (1-366)

date "2023-01-15" |yearday?
; returns 15

year?

Extracts the year from a time object as an integer.

Args: 1

Types: 1 [ Time ]

time Time object to extract year from

returns integer representing the year

date "2023-01-15" |year?
; returns 2023

month?

Extracts the month from a time object as an integer (1-12).

Args: 1

Types: 1 [ Time ]

time Time object to extract month from

returns integer representing the month (1-12)

date "2023-01-15" |month?
; returns 1

days-in-month?

Calculates the number of days in the month of the given time object.

Args: 1

Types: 1 [ Time ]

time Time object to calculate days in month for

returns integer representing the number of days in the month

date "2023-01-15" |days-in-month?
; returns 31

date "2023-02-15" |days-in-month?
; returns 28

time?

Extracts the time part from a time object as a formatted string (hh:mm:ss).

Args: 1

Types: 1 [ Time ]

time Time object to extract time from

returns string representing the time in "hh:mm:ss" format

datetime "2023-01-15T14:30:45" |time?
; returns "14:30:45"

date?

Extracts the date part from a time object as a formatted string (YYYY-MM-DD).

Args: 1

Types: 1 [ Time ]

time Time object to extract date from

returns string representing the date in "YYYY-MM-DD" format

datetime "2023-01-15T14:30:45" |date?
; returns "2023-01-15"

format-imap-date

Formats a time object as an IMAP search date string (DD-Mon-YYYY).

Args: 1

Types: 1 [ Time ]

time Time object to format

returns string representing the date in IMAP search format (DD-Mon-YYYY)

date "2023-01-15" |format-imap-date
; returns "15-Jan-2023"

format-date

Formats a time object using a Go time format layout string. Reference time: Mon Jan 2 15:04:05 MST 2006

Args: 2

Types: 1 [ Time ] 2 [ String ]

time Time object to format

layout String - Go time format layout (reference time

returns string representing the formatted date/time

date "2023-01-15" |format-date "2006-01-02"
; returns "2023-01-15"

date "2023-01-15" |format-date "02/01/2006"
; returns "15/01/2023"

datetime "2023-01-15T14:30:45" |format-date "Mon Jan 2 15:04:05 2006"
; returns "Sun Jan 15 14:30:45 2023"

day?

Extracts the day of month from a time object as an integer (1-31).

Args: 1

Types: 1 [ Time ]

time Time object to extract day from

returns integer representing the day of month (1-31)

date "2023-01-15" |day?
; returns 15

hour?

Extracts the hour from a time object as an integer (0-23).

Args: 1

Types: 1 [ Time ]

time Time object to extract hour from

returns integer representing the hour (0-23)

datetime "2023-01-15T14:30:45" |hour?
; returns 14

minute?

Extracts the minute from a time object as an integer (0-59).

Args: 1

Types: 1 [ Time ]

time Time object to extract minute from

returns integer representing the minute (0-59)

datetime "2023-01-15T14:30:45" |minute?
; returns 30

second?

Extracts the second from a time object as an integer (0-59).

Args: 1

Types: 1 [ Time ]

time Time object to extract second from

returns integer representing the second (0-59)

datetime "2023-01-15T14:30:45" |second?
; returns 45

sleep

Pauses execution for the specified number of milliseconds.

Args: 1

Types: 1 [ Integer ]

milliseconds Integer number of milliseconds to sleep

returns the original milliseconds value

time-it { sleep 10 }
; returns 10

thousands

Multiplies the input by 1000 (useful for unit conversion).

Args: 1

Types: 1 [ Integer ]

n Integer

returns integer multiplied by 1000

5 .thousands
; returns 5000

millions

Multiplies the input by 1000000 (useful for unit conversion).

Args: 1

Types: 1 [ Integer ]

n Integer

returns integer multiplied by 1000000

5 .millions
; returns 5000000

seconds

Converts seconds to milliseconds (multiplies by 1000).

Args: 1

Types: 1 [ Integer ]

n Integer number of seconds

returns integer representing the equivalent number of milliseconds

5 .seconds
; returns 5000

minutes

Converts minutes to milliseconds (multiplies by 60000).

Args: 1

Types: 1 [ Integer ]

n Integer number of minutes

returns integer representing the equivalent number of milliseconds

5 .minutes
; returns 300000

hours

Converts hours to milliseconds (multiplies by 3600000).

Args: 1

Types: 1 [ Integer ]

n Integer number of hours

returns integer representing the equivalent number of milliseconds

5 .hours
; returns 18000000

days

Converts days to milliseconds (multiplies by 86400000).

Args: 1

Types: 1 [ Integer ]

n Integer number of days

returns integer representing the equivalent number of milliseconds

5 .days
; returns 432000000

weeks

Converts weeks to milliseconds (multiplies by 604800000).

Args: 1

Types: 1 [ Integer ]

n Integer number of weeks

returns integer representing the equivalent number of milliseconds

5 .weeks
; returns 3024000000

time-it

Accepts a block, does it and times it's execution time.

Args: 1

Types: 1 [ Block ]

block Block of code to execute and time

returns integer representing execution time in milliseconds

time-it { sleep 100 }
; returns 100

random

Selects a random value from a block of values.

Args: 1

Types: 1 [ Integer ]

block Block of values to select from

returns a randomly selected value from the block

random { 1 2 3 } |type?
; returns integer

random { 1 2 3 } |contains* { 1 2 3 }
; returns true

randomize

Returns a new block or list with the same values as the input but in a randomized (shuffled) order.

Args: 1

Types: 1 [ Block List ]

collection Block or list of values to randomize

returns a new block or list with the same values in a randomized order

randomize { 1 2 3 } |type?
; returns block

randomize { 1 2 3 } |length?
; returns 3

randomize { 1 2 3 } |sort
; returns { 1 2 3 }

randomize list { 1 2 3 } |type?
; returns list

randomize list { 1 2 3 } |length?
; returns 3

randomize list { 1 2 3 } |sort
; returns list { 1 2 3 }

unpack

Flattens a block of blocks or list of lists by one level, combining all inner collections into a single collection.

Args: 1

Types: 1 [ Block ]

collection Block or list of blocks/lists to unpack

returns a flattened block or list with all inner blocks/lists unpacked

unpack { { 123 } { 234 } }
; returns { 123 234 }

unpack { { { 123 } } { 234 } }
; returns { { 123 } 234 }

sample

Randomly selects a specified number of elements from a collection without replacement.

Args: 2

Types: 1 [ Integer ] 2 [ Integer ]

collection Block, list or table to sample from

count Number of random elements to select

returns a new collection with randomly selected elements

sample { 1 2 3 4 } 2 |length?
; returns 2

sample { 123 123 123 123 } 3 |-> 0
; returns 123

max

Finds the maximum value in a block or list of comparable values.

Args: 1

Types: 1 [ Block List Vector Matrix ]

collection Block, list, vector or matrix of comparable values

returns the maximum value in the collection

max { 8 2 10 6 }
; returns 10

max list { 8 2 10 6 }
; returns 10

try { max { } } |type?
; returns error

try { max list { } } |type?
; returns error

max vector { 8 2 10 6 }
; returns 10

max matrix { 2 2 } { 1 5 3 2 }
; returns 5

max\by

Finds the value in a collection that produces the maximum result when transformed by a code block. Returns the original value, not the transformed result.

Args: 2

Types: 1 [ Block List ] 2 [ Block ]

collection Block or list of values

code Block of code to transform each value for comparison

returns the original value that produces the maximum result when transformed by the code block

{ 1 3 2 } |max\by { * -10 }
; returns 1

{ "a" "abc" "ab" } |max\by { .length? }
; returns "abc"

{ 5 -3 2 -8 } |max\by { math/abs }
; returns -8

list { 1 3 2 } |max\by { * -10 }
; returns 1

min

Finds the minimum value in a block or list of comparable values.

Args: 1

Types: 1 [ Block List Vector Matrix ]

collection Block, list, vector or matrix of comparable values

returns the minimum value in the collection

min { 8 2 10 6 }
; returns 2

min list { 8 2 10 6 }
; returns 2

try { min { } } |type?
; returns error

try { min list { } } |type?
; returns error

min vector { 8 2 10 6 }
; returns 2

min matrix { 2 2 } { 1 5 3 2 }
; returns 1

min\by

Finds the value in a collection that produces the minimum result when transformed by a code block. Returns the original value, not the transformed result.

Args: 2

Types: 1 [ Block List ] 2 [ Block ]

collection Block or list of values

code Block of code to transform each value for comparison

returns the original value that produces the minimum result when transformed by the code block

{ 3 1 2 } |min\by { * -10 }
; returns 3

{ "a" "abc" "ab" } |min\by { .length? }
; returns "a"

{ 5 -3 2 -8 } |min\by { math/abs }
; returns 2

list { 3 1 2 } |min\by { * -10 }
; returns 3

avg

Calculates the arithmetic mean (average) of numeric values in a collection.

Args: 1

Types: 1 [ Block Vector Matrix ]

collection Block, list, vector or matrix of numeric values

returns the arithmetic mean (average) of the values as a decimal

avg { 8 2 10 6 }
; returns 6.5

avg list { 8 2 10 6 }
; returns 6.5

avg { 1 2 3 }
; returns 2

try { avg { } } |type?
; returns error

try { avg list { } } |type?
; returns error

avg vector { 1 2 3 4 }
; returns 2.5

avg matrix { 2 2 } { 1 2 3 4 }
; returns 2.5

avg\by

Calculates the average of the results of transforming each value in a collection by a code block. Returns the average of all transformed results.

Args: 2

Types: 1 [ Block List ] 2 [ Block ]

collection Block or list of values

code Block of code to transform each value before averaging

returns the average of all transformed results as a decimal

{ 1 2 3 } |avg\by { * 2 }
; returns 4

{ "a" "abc" "ab" } |avg\by { .length? }
; returns 2

{ 10 20 30 } |avg\by { / 10 }
; returns 2

list { 2 4 6 } |avg\by { + 1 }
; returns 5

sum

Calculates the sum of all numeric values in a collection.

Args: 1

Types: 1 [ Block Vector Matrix ]

collection Block, list, vector or matrix of numeric values

returns the sum of all values (integer if all values are integers, decimal otherwise)

sum { 8 2 10 6 }
; returns 26

sum { 8 2 10 6.5 }
; returns 26.5

sum { }
; returns 0

sum list { 8 2 10 6 }
; returns 26

sum list { 8 2 10 6.5 }
; returns 26.5

sum list { }
; returns 0

sum vector { 1 2 3 4 }
; returns 10

sum matrix { 2 3 } { 1 2 3 4 5 6 }
; returns 21

sum\by

Sums the results of transforming each value in a collection by a code block. Returns the sum of all transformed results.

Args: 2

Types: 1 [ Block List ] 2 [ Block ]

collection Block or list of values

code Block of code to transform each value before summing

returns the sum of all transformed results (integer if all results are integers, decimal otherwise)

{ 1 2 3 } |sum\by { * 2 }
; returns 12

{ "a" "abc" "ab" } |sum\by { .length? }
; returns 6

{ 1.5 2.5 3.5 } |sum\by { * 2 }
; returns 15

list { 1 2 3 4 } |sum\by { + 10 }
; returns 50

mul

Calculates the product of all numeric values in a collection.

Args: 1

Types: 1 [ Block Vector ]

collection Block, list or vector of numeric values

returns the product of all values (integer if all values are integers, decimal otherwise)

mul { 1 2 3 4 5 }
; returns 120

mul { 1 2 3.3 4 5 }
; returns 132

mul { 2 3 4 }
; returns 24

first

Retrieves the first item from a collection (block, list, string, table, vector, matrix, or bytes).

Args: 1

collection Block, list, string, table, vector, matrix or bytes to get the first item from

returns the first item in the collection (for matrix: first row as vector)

first { 1 2 3 4 }
; returns 1

first "abcde"
; returns "a"

first list { 1 2 3 }
; returns 1

first { { "nested" } 2 3 }
; returns { "nested" }

table { 'a } { 42 } |format\xlsx |first |> 0
; returns true

first vector { 1 2 3 }
; returns 1

first matrix { 2 3 } { 1 2 3 4 5 6 } |type?
; returns vector

first matrix { 2 3 } { 1 2 3 4 5 6 } |first
; returns 1

rest

Creates a new collection with all items except the first one from the input collection.

Args: 1

collection Block, list, string, vector or matrix to get all but the first item from

returns a new collection containing all items except the first one (for matrix: all rows except first)

rest { 1 2 3 4 }
; returns { 2 3 4 }

rest "abcde"
; returns "bcde"

rest list { 1 2 3 }
; returns list { 2 3 }

rest { 1 }
; returns { }

rest vector { 1 2 3 } |first
; returns 2

rest matrix { 3 2 } { 1 2 3 4 5 6 } |rows?
; returns 2

rest\from

Creates a new collection with all items starting from the specified position in the input collection.

Args: 2

Types: 1 [ Block List String Vector Matrix ] 2 [ Integer ]

collection Block, list, string, vector or matrix to get items from

n Integer position to start from (0-based)

returns a new collection containing all items starting from position n (for matrix: from row n)

rest\from { 1 2 3 4 5 6 } 3
; returns { 4 5 6 }

rest\from "abcdefg" 1
; returns "bcdefg"

rest\from list { 1 2 3 4 } 2
; returns list { 3 4 }

rest\from { 1 2 3 } 0
; returns { 1 2 3 }

rest\from vector { 1 2 3 4 } 2 |first
; returns 3

rest\from matrix { 3 2 } { 1 2 3 4 5 6 } 1 |rows?
; returns 2

tail

Creates a new collection with the last n items from the input collection, or all but the first |n| items if n is negative.

Args: 2

collection Block, list, string, table, vector or matrix to get the last items from

n Number of items to retrieve from the end; if negative, all but the first |n| items

returns a new collection containing the last n items (for matrix: last n rows), or all except the first |n| if n is negative

tail { 1 2 3 4 5 6 7 } 3
; returns { 5 6 7 }

tail "abcdefg" 4
; returns "defg"

tail list { 1 2 3 4 } 1
; returns list { 4 }

tail { 1 2 } 5
; returns { 1 2 }

tail vector { 1 2 3 4 } 2 |first
; returns 3

tail matrix { 3 2 } { 1 2 3 4 5 6 } 2 |rows?
; returns 2

tail { 1 2 3 4 5 } -1
; returns { 2 3 4 5 }

tail { 1 2 3 4 5 } -2
; returns { 3 4 5 }

tail "abcde" -1
; returns "bcde"

tail "abcde" -2
; returns "cde"

tail list { 1 2 3 4 5 } -1
; returns list { 2 3 4 5 }

second

Retrieves the second item from a collection (block, list, string, vector, matrix, or bytes).

Args: 1

collection Block, list, string, vector or matrix to get the second item from

returns the second item in the collection (for matrix: second row as vector)

second { 123 234 345 }
; returns 234

second "abc"
; returns "b"

second list { 10 20 30 }
; returns 20

second vector { 1 2 3 }
; returns 2

second matrix { 3 2 } { 1 2 3 4 5 6 } |first
; returns 3

table { 'a } { 1 } |format\xlsx |second |type?
; returns integer

third

Retrieves the third item from a collection (block, list, string, vector, matrix, or bytes).

Args: 1

collection Block, list, string, vector or matrix to get the third item from

returns the third item in the collection (for matrix: third row as vector)

third { 123 234 345 }
; returns 345

third "abcde"
; returns "c"

third list { 10 20 30 40 }
; returns 30

third vector { 1 2 3 4 }
; returns 3

third matrix { 4 2 } { 1 2 3 4 5 6 7 8 } |first
; returns 5

table { 'a } { 1 } |format\xlsx |third |type?
; returns integer

last

Retrieves the last item from a collection (block, list, string, vector, matrix, or bytes).

Args: 1

collection Block, list, string, vector, matrix or bytes to get the last item from

returns the last item in the collection (for matrix: last row as vector)

last { 1 2 }
; returns 2

last "abcd"
; returns "d"

last list { 4 5 6 }
; returns 6

try { last { } } |type?
; returns error

last vector { 1 2 3 }
; returns 3

last matrix { 2 3 } { 1 2 3 4 5 6 } |first
; returns 4

table { 'a } { 42 } |format\xlsx |last |> -1
; returns true

before-last

Creates a new collection with all items except the last one from the input collection.

Args: 1

collection Block, list, string, vector or matrix to get all but the last item from

returns a new collection containing all items except the last one (for matrix: all rows except last)

before-last { 1 2 3 4 }
; returns { 1 2 3 }

before-last "abcd"
; returns "abc"

before-last list { 4 5 6 }
; returns list { 4 5 }

before-last { 1 }
; returns { }

try { all-before-last { } } |type?
; returns error

before-last vector { 1 2 3 } |first
; returns 1

before-last matrix { 3 2 } { 1 2 3 4 5 6 } |rows?
; returns 2

head

Creates a new collection with the first n items from the input collection, or all but the last |n| items if n is negative.

Args: 2

collection Block, list, string or table to get the first items from

n Number of items to retrieve (if positive) or number to exclude from the end (if negative)

returns a new collection containing the first n items or all but the last |n| items

head { 4 5 6 7 } 3
; returns { 4 5 6 }

head "abcdefg" 2
; returns "ab"

head "abcdefg" 4
; returns "abcd"

head list { 10 20 30 40 } 2
; returns list { 10 20 }

head { 4 5 6 7 } -2
; returns { 4 5 }

head "abcdefg" -1
; returns "abcdef"

head "abcdefg" -5
; returns "ab"

head list { 10 20 30 40 } -1
; returns list { 10 20 30 }

nth

Retrieves the item at the specified position (1-based indexing) from a collection.

Args: 2

collection Block, list, string, table, vector, matrix or bytes to get an item from

n Position of the item to retrieve (1-based)

returns the item at position n in the collection

nth { 1 2 3 4 5 } 4
; returns 4

nth { "a" "b" "c" "d" "e" } 2
; returns "b"

nth list { 10 20 30 40 } 2
; returns 20

nth list { 10 20 30 40 } 0
; correctly causes error:
; Index 0 is too low (minimum is 1) 

table { 'a } { 1 } |format\xlsx |nth 1 |type?
; returns integer

values

Extracts all values from a dictionary and returns them as a list.

Args: 1

dict Dictionary object to extract values from

returns list containing all values from the dictionary

dict { "a" 1 "b" 2 "c" 3 } |values
; returns list { 1 2 3 }

dict { "x" 10 "y" 20 } |values |length?
; returns 2

sort

Creates a new collection with items sorted in ascending order.

Args: 1

collection Block, list or string to sort

returns a new collection with items sorted in ascending order

sort { 6 12 1 }
; returns { 1 6 12 }

sort x: { 6 12 1 } x
; returns { 6 12 1 }

sort { "b" "c" "a" }
; returns { "a" "b" "c" }

sort list { 5 3 1 4 }
; returns list { 1 3 4 5 }

sort "cba"
; returns "abc"

sort { 3.14 1.41 2.71 }
; returns { 1.41 2.71 3.14 }

sort!

Sorts a block or list in-place in ascending order and returns the modified collection.

Args: 1

collection Reference to a block or list to sort in-place

returns the sorted collection (same reference, modified in-place)

x: { 6 12 1 } , sort! x
; correctly causes error:
; `sort!` expected Block, List for argument 1, got Block 

x: ref { 1 6 12 } , sort! x , x
; returns { 1 6 12 }

x: ref list { 5 3 1 4 } , sort! x , x
; returns list { 1 3 4 5 }

sort\by

Creates a new collection with items sorted according to a custom comparison function.

Args: 2

Types: 2 [ Function ]

collection Block or list to sort

comparator Function that takes two arguments and returns a truthy value if they are in the correct order

returns a new collection with items sorted according to the comparator function

sort\by { 6 12 1 } fn { a b } { a < b }
; returns { 1 6 12 }

sort\by { 6 12 1 } fn { a b } { a > b }
; returns { 12 6 1 }

sort\by { { x 6 } { x 12 } { x 1 } } fn { a b } { second a |< second b }
; returns { { x 1 } { x 6 } { x 12 } }

sort\by list { 5 3 1 4 } fn { a b } { a > b }
; returns list { 5 4 3 1 }

sort\by\key

Efficiently sorts a collection by pre-computing a sort key for each element using a key function. Much faster than sort\by for large datasets (Schwartzian Transform).

Args: 2

Types: 2 [ Block ]

collection Block or list to sort

key-fn Block of code that transforms each value to a sortable key (evaluated once per element)

returns a new collection with items sorted according to the computed keys

sort\by\key { 6 12 1 } { * -1 }
; returns { 12 6 1 }

sort\by\key { 6 12 1 } { + 0 }
; returns { 1 6 12 }

sort\by\key { { x 6 } { x 12 } { x 1 } } { .second }
; returns { { x 1 } { x 6 } { x 12 } }

sort\by\key { "abc" "a" "ab" } { .length? }
; returns { "a" "ab" "abc" }

sort\by\key list { 5 3 1 4 } { * -1 }
; returns list { 5 4 3 1 }

unique

Creates a new collection with duplicate values removed, keeping only the first occurrence of each value.

Args: 1

collection Block, list or string to remove duplicates from

returns a new collection with duplicate values removed

list { 3 2 3 5 3 2 } .unique |sort
; returns list { 2 3 5 }

unique list { 1 1 2 2 3 } |sort
; returns list { 1 2 3 }

unique list { 1 1 2 2 } |sort
; returns list { 1 2 }

unique { 1 1 2 2 3 } |sort
; returns { 1 2 3 }

unique { 1 1 2 2 } |sort
; returns { 1 2 }

unique "aabbc" |length?
; returns 3

unique "ab" |length?
; returns 2

reverse

Creates a new collection with items in reverse order from the input collection.

Args: 1

collection Block, list or string to reverse

returns a new collection with items in reverse order

reverse { 3 1 2 3 }
; returns { 3 2 1 3 }

reverse "abcd"
; returns "dcba"

reverse list { 1 2 3 4 }
; returns list { 4 3 2 1 }

reverse { }
; returns { }

reverse!

Reverses a block or list in-place and returns the modified collection.

Args: 1

collection Reference to a block or list to reverse in-place

returns the reversed collection (same reference, modified in-place)

reverse! { 3 1 2 3 }
; correctly causes error:
; `reverse!` expected Block, String, List for argument 1, got Block 

reverse! ref { 3 2 1 3 }
; returns { 3 2 1 3 }

x: ref list { 1 2 3 } , reverse! x , x
; returns list { 3 2 1 }

prepend

Returns a new block with the value prepended. The original block is not modified.

Args: 2

block Block to prepend to

value Value to put at the beginning of the new block

returns a new block with value prepended; the original block is not modified

{ 2 3 } |prepend 1
; returns { 1 2 3 }

{ } |prepend 1
; returns { 1 }

{ 2 3 } |prepend { 1 }
; returns { { 1 } 2 3 }

prepend 1 2
; correctly causes error:
; `prepend` expected Block for argument 1, got Integer 

concat

Joins two series values together.

Args: 2

Types: 1 [ Integer String Block Uri ] 2 [ String Integer Uri ]

value1 First value (string, integer, block, uri) to concatenate

value2 Second value to concatenate with the first

returns result of concatenating the two values

"abcd" .concat "cde"
; returns "abcdcde"

concat { 1 2 3 4 } { 2 4 5 }
; returns { 1 2 3 4 2 4 5 }

123 .concat "abc"
; returns "123abc"

https://example.com/ .concat "path" |type?
; returns uri

{ 1 } .concat { 2 } .concat { 3 }
; returns { 1 2 3 }

_++

Joins two values together, with behavior depending on types: concatenates strings, joins blocks, merges dictionaries, etc.

Args: 2

Types: 1 [ String Block Dict TableRow Time Uri ] 2 [ String Integer Decimal Secret Uri Block Dict ]

value1 First value (string, block, dict, etc.)

value2 Second value to join

returns result of joining the values, type depends on input types

"A" ++ "b"
; returns "Ab"

"A" ++ 1
; returns "A1"

{ 1 2 } ++ { 3 4 }
; returns { 1 2 3 4 }

dict { "a" 1 } || ++ { "b" 2 }
; returns dict { a 1 b 2 }

dict { "a" 1 } || ++ dict { "b" 2 }
; returns dict { a 1 b 2 }

( file "a/b" ) ++ ( file "c/d" ) |kind?
; returns file-uri

union

Combines two collections, removing any duplicate values to create a union of all unique values.

Args: 2

Types: 1 [ Block List ] 2 [ Block List ]

collection1 First block or list

collection2 Second block or list

returns a new collection containing all unique values from both collections

union { 1 2 3 4 } { 2 4 5 } |length?
; returns 5

union list { 1 2 3 4 } list { 2 4 5 } |length?
; returns 5

union { 8 2 } { 1 9 } |sort
; returns { 1 2 8 9 }

union { 1 2 } { } |sort
; returns { 1 2 }

union { } { 1 9 } |sort
; returns { 1 9 }

union { } { }
; returns { }

union list { 1 2 } list { 1 2 3 4 } |sort
; returns list { 1 2 3 4 }

union list { 1 2 } list { 1 } |sort
; returns list { 1 2 }

union list { 1 2 } list { } |sort
; returns list { 1 2 }

union list { } list { 1 2 } |sort
; returns list { 1 2 }

union list { } list { }
; returns list { }

range

Creates a block containing all integers from start to end, inclusive. Requires start <= end and at most 16777216 elements.

Args: 2

Types: 1 [ Integer ] 2 [ Integer ]

start Integer starting value (inclusive)

end Integer ending value (inclusive)

returns a block containing all integers from start to end, inclusive

range 1 5
; returns { 1 2 3 4 5 }

range 5 10
; returns { 5 6 7 8 9 10 }

range -2 2
; returns { -2 -1 0 1 2 }

range 3 3
; returns { 3 }

is-empty

Checks if a collection is empty, returning true if empty and false otherwise.

Args: 1

Types: 2 [ String Dict List Block Table Vector ]

collection String, block, dict, list, table, context or vector to check

returns boolean true if the collection is empty, false otherwise

{ } .is-empty
; returns true

dict { } |is-empty
; returns true

table { 'a 'b } { } |is-empty
; returns true

"abc" .is-empty
; returns false

{ 1 2 3 } .is-empty
; returns false

length?

Returns the number of elements in a collection.

Args: 1

collection String, block, dict, list, table, context, vector or bytes to measure

returns integer count of elements in the collection

{ 1 2 3 } .length?
; returns 3

length? "abcd"
; returns 4

table { 'val } { 1 2 3 4 } |length?
; returns 4

vector { 10 20 30 } |length?
; returns 3

dict { "a" 1 "b" 2 } |length?
; returns 2

list { 1 2 3 4 5 } |length?
; returns 5

table { 'a } { 1 } |format\xlsx |length? |> 100
; returns true

max-idx?

Returns the maximum valid index in a collection (length? - 1).

Args: 1

collection String, block, dict, list, table, context or vector to measure

returns integer index of the last element in the collection

{ 1 2 3 } .max-idx?
; returns 2

max-idx? "abcd"
; returns 3

table { 'val } { 1 2 3 4 } |max-idx?
; returns 3

vector { 10 20 30 } |max-idx?
; returns 2

keys

Extracts the keys from a dictionary or column names from a table as a block.

Args: 1

collection Dict or table to extract keys from

returns block containing all keys from the dictionary or column names from the table

dict { "a" 1 "b" 2 "c" 3 } |keys |length?
; returns 3

table { "a" "b" "c" } { 1 2 3 } |keys |length?
; returns 3

_->

Accesses a value in a collection by index or key (0-based indexing for blocks and lists).

Args: 2

collection Block, list, dict or other indexable collection (including refs)

index Index or key to access

returns value at the specified index or key

{ 23 34 45 } -> 1
; returns 34

{ "a" "b" "c" } -> 0
; returns "a"

dict { "a" 1 "b" 2 } |-> "b"
; returns 2

ref { 23 34 45 } |-> 1
; returns 34

ref dict { "a" 1 "b" 2 } |-> "b"
; returns 2

ref list { 10 20 30 } |-> 0
; returns 10

_<-

Accesses a value in a collection by index or key, with reversed argument order (0-based indexing for blocks and lists).

Args: 2

index Index or key to access

collection Block, list, dict or other indexable collection

returns value at the specified index or key

0 <- { 23 34 45 }
; returns 23

2 <- { "a" "b" "c" }
; returns "c"

"a" <- dict { "a" 1 "b" 2 }
; returns 1

_<~

Accesses a value in a collection by index with reversed argument order (1-based indexing).

Args: 2

index Index to access (1-based)

collection Block, list or other indexable collection

returns value at the specified index

2 <~ { 23 34 45 }
; returns 34

1 <~ { "a" "b" "c" }
; returns "a"

_~>

Accesses a value in a collection by index (1-based indexing).

Args: 2

collection Block, list or other indexable collection

index Index to access (0-based)

returns value at the specified index

{ 23 34 45 } ~> 1
; returns 23

{ "a" "b" "c" } ~> 1
; returns "a"

intersection

Finds the common elements between two collections, returning only values that appear in both.

Args: 2

Types: 1 [ String Block List ] 2 [ String Block List ]

collection1 First string, block or list

collection2 Second string, block or list (same type as first)

returns a new collection containing only values that appear in both input collections

"abcd" .intersection "cde"
; returns "cd"

intersection { 1 2 3 4 } { 2 4 5 }
; returns { 2 4 }

intersection { 1 3 5 6 } { 2 3 4 5 }
; returns { 3 5 }

intersection { 1 2 3 } { }
; returns { }

intersection { } { 2 3 4 }
; returns { }

intersection { 1 2 3 } { 4 5 6 }
; returns { }

intersection { } { }
; returns { }

intersection list { 1 3 5 6 } list { 2 3 4 5 }
; returns list { 3 5 }

intersection list { 1 2 3 } list { }
; returns list { }

intersection list { } list { 2 3 4 }
; returns list { }

intersection list { 1 2 3 } list { 4 5 6 }
; returns list { }

intersection list { } list { }
; returns list { }

intersection\by

Finds the intersection of two collections using a custom comparison function to determine matching elements.

Args: 3

Types: 1 [ String Block List ] 2 [ Function String Block ] 3 [ Function ]

collection1 First string or block

collection2 Second string or block

comparator Function that takes two arguments and returns a truthy value if they should be considered matching

returns a new collection containing values from the first collection that match with values from the second collection according to the comparator

intersection\by "foobar" "fbx" fn { a b } { a .contains b }
; returns "fb"

intersection\by "fooBar" "Fbx" fn { a b } { a .lower .contains lower b }
; returns "fB"

intersection\by { "foo" 33 } { 33 33 } fn { a b } { a .contains b }
; returns { 33 }

intersection\by { "foo" "bar" 33 } { 42 } fn { a b } { map a {  } |contains b .type? }
; returns { 33 }

intersection\by { { "foo" x } { "bar" y } } { { "bar" z } } fn { a b } { map a {  } |contains first b }
; returns { { "bar" y } }

difference

Creates a new collection containing elements from the first collection that are not present in the second collection.

Args: 2

Types: 1 [ String Block List ] 2 [ String Block List ]

collection1 First string, block or list

collection2 Second string, block or list (same type as first)

returns a new collection containing values from the first collection that do not appear in the second collection

"abcde" .difference "cde"
; returns "ab"

difference { 1 2 3 4 } { 2 4 }
; returns { 1 3 }

difference list { "Bob" "Sal" "Joe" } list { "Joe" }
; returns list { "Bob" "Sal" }

difference "abc" "bc"
; returns "a"

difference "abc" "abc"
; returns ""

difference "abc" ""
; returns "abc"

difference "" ""
; returns ""

difference { 1 3 5 6 } { 2 3 4 5 }
; returns { 1 6 }

difference { 1 2 3 } { }
; returns { 1 2 3 }

difference { } { 2 3 4 }
; returns { }

difference { } { }
; returns { }

difference list { 1 3 5 6 } list { 2 3 4 5 }
; returns list { 1 6 }

difference list { 1 2 3 } list { }
; returns list { 1 2 3 }

difference list { } list { 2 3 4 }
; returns list { }

difference list { } list { }
; returns list { }

transpose

Transposes a matrix (block of blocks), converting rows to columns and columns to rows.

Args: 1

Types: 1 [ Block ]

matrix Block of blocks representing a matrix

returns transposed matrix (rows become columns and columns become rows)

{ { 1 2 3 } { 4 5 6 } } .transpose
; returns { { 1 4 } { 2 5 } { 3 6 } }

{ { 1 4 } { 2 5 } { 3 6 } } .transpose
; returns { { 1 2 3 } { 4 5 6 } }

zip

Combines two same-size collections into a block of pairs, where each pair contains corresponding elements from both collections.

Args: 2

Types: 1 [ Block List ] 2 [ Block List ]

collection1 First block or list

collection2 Second block or list (must be same length? as first)

returns a block of blocks, where each inner block contains paired elements from both collections

zip { 1 2 3 } { "a" "b" "c" }
; returns { { 1 "a" } { 2 "b" } { 3 "c" } }

zip { 1 2 } { 10 20 }
; returns { { 1 10 } { 2 20 } }

zip list { 1 2 3 } list { "a" "b" "c" }
; returns { { 1 "a" } { 2 "b" } { 3 "c" } }

try { zip { 1 2 3 } { "a" "b" } } |type?
; returns error

try { zip { } { } } |type?
; returns error

remove-last!

Removes the last element from a block in-place and returns the modified block.

Args: 1

Types: 1 [ Word ]

word Word referring to a block to modify

returns the modified block with the last element removed

var 'x ref { 1 2 3 4 } remove-last! 'x x
; returns { 1 2 3 }

var 'x ref { 1 2 3 4 } remove-last! 'x
; returns { 1 2 3 }

append!

Appends a value to a block, list or string in-place and returns the modified collection.

Args: 2

Types: 2 [ String Block List ]

value Value to append

word Word referring to a block, list or string to modify

returns the modified collection with the value appended

var 'x ref { 1 2 3 } append! 4 'x , x
; returns { 1 2 3 4 }

var 's "hello" append! " world" 's , s
; returns "hello world"

update!

Updates the value at a specific index in a block or list in-place and returns the modified collection (0-based indexing).

Args: 3

Types: 1 [ Block List ] 2 [ Integer ]

collection Reference to a block or list to modify

index Index of the element to change (0-based)

value New value to set at the specified index

returns the modified collection with the value changed at the specified index

x: ref { 1 222 3 } update! x 1 222 , x
; returns { 1 222 3 }

x: ref list { "a" "b" "c" } update! x 0 "X" , x
; returns list { "X" "b" "c" }

x: ref { 10 20 99 } update! x 2 99 , x
; returns { 10 20 99 }

update\with!

Updates the value at a specific index by evaluating a code block with the current value injected and storing the result (0-based indexing).

Args: 3

Types: 1 [ Block List ] 2 [ Integer ] 3 [ Block ]

collection Reference to a block or list to modify

index Index of the element to transform (0-based)

transform Block of code that receives the current value and returns the new value

returns the modified collection with the value at the index transformed by the code block

x: ref { 10 40 30 } update\with! x 1 { * 2 } , x
; returns { 10 40 30 }

x: ref { 101 2 3 } update\with! x 0 { + 100 } , x
; returns { 101 2 3 }

x: ref { "a" "b!" "c" } update\with! x 1 { .concat "!" } , x
; returns { "a" "b!" "c" }

update\pos!

Updates the value at a specific position in a block or list in-place and returns the modified collection (1-based indexing).

Args: 3

Types: 1 [ Block List ] 2 [ Integer ]

collection Reference to a block or list to modify

position Position of the element to change (1-based)

value New value to set at the specified position

returns the modified collection with the value changed at the specified position

x: ref { 1 222 3 } update\pos! x 2 222 , x
; returns { 1 222 3 }

x: ref list { "a" "b" "c" } update\pos! x 1 "X" , x
; returns list { "X" "b" "c" }

x: ref { 10 20 99 } update\pos! x 3 99 , x
; returns { 10 20 99 }

change\nth!

Updates the value at a specific position in a block or list in-place and returns the modified collection (1-based indexing).

Args: 3

Types: 1 [ Block List ] 2 [ Integer ]

collection Block or List to update.

index Integer 1-based position.

value New value for the position.

returns the updated collection.

x: ref { 1 222 3 } change\nth! x 2 222 , x
; returns { 1 222 3 }

append\each!

Appends each value from a block to a collection (block, list or string) in-place and returns the modified collection.

Args: 2

Types: 1 [ Block ] 2 [ Word Block ]

values Block of values to append

word Word referring to a block, list or string to modify (or a mutable block value)

returns the modified collection with each value from the block appended

var 'x ref { 1 2 3 } append\each! { 4 5 6 } 'x , x
; returns { 1 2 3 4 5 6 }

var 'x ref { 1 2 } append\each! { 3 4 5 6 } 'x , x
; returns { 1 2 3 4 5 6 }

var 's "hello" append\each! { " " "world" "!" } 's , s
; returns "hello world!"

var 'l ref list { 10 20 } append\each! { 30 40 } 'l , l
; returns list { 10 20 30 40 }

b: ref { 1 2 } append\each! { 3 4 } b
; returns { 1 2 3 4 }

peek

Returns the current value at a block's cursor position without advancing the cursor.

Args: 1

Types: 1 [ Block ]

block Block to peek at

returns the current value at the block's cursor position without advancing the cursor

x: { 1 2 3 } peek x
; returns 1

pop

Returns the current value at a block's cursor position and advances the cursor.

Args: 1

Types: 1 [ Block ]

block Block to pop from

returns the current value at the block's cursor position, advancing the cursor

x: { 1 2 3 } pop x
; returns 1

pos

Returns the current cursor position in a block.

Args: 1

Types: 1 [ Block ]

block Block to get position from

returns the current cursor position in the block

x: { 1 2 3 } pos x
; returns 0

x: { 1 2 3 } pos next x
; returns 1

next

Advances the cursor position in a block and returns the block.

Args: 1

Types: 1 [ Block ]

block Block to advance cursor in

returns the block with its cursor advanced to the next position

x: { 11 22 33 } peek next next x
; returns 33

at

Sets the cursor position in a block to the specified index and returns the block.

Args: 2

block Block to set cursor position in

position Integer position to set the cursor to (0-based)

returns the block with its cursor set to the specified position

{ 1 2 3 4 5 } .at 0 |peek
; returns 1

{ 1 2 3 4 5 } .at 2 |peek
; returns 3

{ 1 2 3 4 5 } .at 4 |peek
; returns 5

x: { 10 20 30 } at x 1 |pos
; returns 1

{ "a" "b" "c" } .at 0 |pop
; returns "a"

evals

Takes a block of Rye values and evaluates each value or expression.

Args: 1

Types: 1 [ Block Word ]

block-or-word Block of expressions to evaluate, or a word to resolve

returns block of evaluated results (for a block input) or the resolved word value

x: 1 y: 2 evals { x y }
; returns { 1 2 }

x: 1 y: 2 evals { 1 y }
; returns { 1 2 }

x: 1 y: 2 try { evals { z y } } |type?
; returns error

evals\with

Evaluate a block with injecting the first argument.

Args: 2

Types: 2 [ Block ]

value Value injected into each expression

block Block of expressions to evaluate

returns block of evaluated results

x: 1 y: 2 evals\with 10 { + x , * y }
; returns { 11 20 }

x: 1 y: 2 evals\with 100 { + 10 , * 8.9 }
; returns { 110 890 }

integer

Tries to change a Rye value (like string) to integer.

Args: 1

value String or decimal value to convert to an integer

returns An integer value

integer "1234"
; returns 1234

integer 45.67
; returns 45

integer "abc"
; correctly causes error:
; `integer`: strconv.Atoi: parsing "abc": invalid syntax 

decimal

Tries to change a Rye value (like string) to decimal.

Args: 1

value String value to convert to a decimal

returns A decimal value

decimal "123.4"
; returns 123.4

decimal "abc"
; correctly causes error:
; `decimal`: strconv.ParseFloat: parsing "abc": invalid syntax 

string

Tries to turn a Rye value to string.

Args: 1

value Any Rye value to convert to a string

returns A string representation of the value

string 'test
; returns "test"

string 123
; returns "123"

string 123.4
; returns "123.4"

string "test"
; returns ""test""

string true
; returns "true"

bytes

Creates a Bytes value. Accepts an integer (creates that many zero bytes), a hex-encoded string, or a block of integers in range 0..255.

Args: 1

value Integer (number of zero bytes), hex-encoded String, or Block of integers 0..255

returns A Bytes value

bytes 0 |length?
; returns 0

bytes 5 |length?
; returns 5

bytes 5 |first
; returns 0

bytes "ff" |first
; returns 255

bytes { 104 101 108 108 111 } |length?
; returns 5

bytes "zz"
; correctly causes error:
; `bytes`: encoding/hex: invalid byte: U+007A 'z' 

bytes { 300 }
; correctly causes error:
; `bytes`: byte value 300 out of range 0..255 at position 0 

bytes { "x" }
; correctly causes error:
; `bytes` expected Integer for argument 1, got String 

uri

Tries to change Rye value to an URI.

Args: 1

value String to convert to a URI.

returns URI value.

uri "https://example.com"
; returns https://example.com

file

Tries to change Rye value to a file.

Args: 1

value String or Integer to convert to a file URI.

returns file URI value.

file "example.txt"
; returns example.txt

file 123
; returns 123

char

Tries to turn a Rye value (like integer) to ascii character.

Args: 1

value Integer representing an ASCII code point

returns A string containing the character corresponding to the ASCII code

char 42
; returns "*"

char "*"
; correctly causes error:
; `char` expected Integer for argument 1, got String 

ascii

Tries to turn a single character string to its ASCII code integer.

Args: 1

value String containing a single character

returns An integer representing the ASCII code of the character

ascii "*"
; returns 42

ascii "A"
; returns 65

ascii "ab"
; correctly causes error:
; `ascii`: String must contain exactly one character 

ascii 42
; correctly causes error:
; `ascii` expected String for argument 1, got Integer 

block

Turns a List, Vector, or TableRow to a Block

Args: 1

value List, Vector, or TableRow to convert to a block

returns A block containing the same elements as the input

list [ 1 2 3 ] |block |type?
; returns block

list [ 1 2 3 ] |block |first
; returns 1

vector [ 1 2 3 ] |block
; returns { 1 2 3 }

table { 'a 'b } { 1 2 3 4 } |-> 0 |block
; returns { 1 2 }

word

Tries to change a Rye value to a word with same name.

Args: 1

value String or word-like value to convert to a word

returns A word with the same name as the input value

word "test"
; returns test

word 123
; correctly causes error:
; `word` expected String, Word, Opword, Pipeword, Xword, EXword for argument 1, got Integer 

is-string

Returns true if value is a string.

Args: 1

value Any Rye value to test

returns Boolean true if the value is a string, false otherwise

is-string "test"
; returns true

is-string 'test
; returns false

is-string 123
; returns false

is-integer

Returns true if value is an integer.

Args: 1

value Any Rye value to test

returns Boolean true if the value is an integer, false otherwise

is-integer 123
; returns true

is-integer 123.4
; returns false

is-integer "123"
; returns false

is-decimal

Returns true if value is a decimal.

Args: 1

value Any Rye value to test

returns Boolean true if the value is a decimal, false otherwise

is-decimal 123.4
; returns true

is-decimal 123
; returns false

is-decimal "123.4"
; returns false

is-number

Returns true if value is a number (integer or decimal).

Args: 1

value Any Rye value to test

returns Boolean true if the value is a number (integer or decimal), false otherwise

is-number 123
; returns true

is-number 123.4
; returns true

is-number "123"
; returns false

type?

Returns the type of Rye value as a word.

Args: 1

value Any Rye value to check the type of

returns A word representing the type of the value

type? "test"
; returns string

type? 123.4
; returns decimal

kind?

Returns the kind of Rye value as a word.

Args: 1

value Any Rye value to check the kind of

returns A word representing the kind of the value

kind? file
; returns file-uri

types?

Returns the types of Rye values in a block or table row as a block of words.

Args: 1

Types: 1 [ Block Table TableRow ]

collection A block, table, or table row containing values to check types of

returns A block of words representing the types of each value in the collection

types? { "test" 123 }
; returns { string integer }

dump

Returns (dumps) Rye code representing the object.

Args: 1

value Any Rye value to dump as code

returns A string containing the Rye code representation of the value

dump 123
; returns "123"

dump "string"
; returns ""string""

does { 1 } |dump
; returns "fn { } { 1 }"

mold

Turn value to it's string representation.

Args: 1

value Any Rye value to convert to a string representation

returns A string containing the representation of the value

mold 123
; returns "123"

mold { 123 }
; returns "{ 123 }"

mold\nowrap

Turn value to it's string representation. Doesn't wrap the blocks

Args: 1

value Any Rye value to convert to a string representation

returns A string containing the representation of the value without block wrapping

mold\nowrap 123
; returns "123"

mold\nowrap { 123 }
; returns "123"

mold\nowrap { 123 234 }
; returns "123 234"

assure-kind

Assuring kind.

Args: 2

Types: 1 [ Dict ] 2 [ Kind ]

value Dict to convert to a specific kind

kind Kind to convert the value to

returns A new context of the specified kind

person: kind 'person { name: "" age: 0 } assure-kind dict { "name" "John" "age" 30 } person |type?
; returns context

method

Registers a method (generic function).

Args: 3

kind Word representing the kind for which to register the function

method Word representing the method name

function Function to register for the kind and method

returns The registered function; method fn [ a b ] [ a + b ] // tagwords are temporary here

method 'integer 'add fn { a b } { a + b } |type?
; returns function

kind

Creates new kind.

Args: 2

Types: 1 [ Word ] 2 [ Block ]

name Word that will be the name of the kind

spec Block containing the specification for the kind

returns A new kind object

kind 'person { name: "" age: 0 } |type?
; returns kind

secret

Creates a secret from a string.

Args: 1

value String value to convert to a secret

returns A secret value that hides the string from casual inspection

secret "password" |type?
; returns secret

secret "password" |reveal
; returns "password"

secret 123
; correctly causes error:
; `secret` expected String for argument 1, got Integer 

reveal

Reveals the secret value.

Args: 1

secret Secret value to reveal

returns The string value contained in the secret

secret "password" |reveal
; returns "password"

secret "test123" |reveal
; returns "test123"

reveal "not-a-secret"
; correctly causes error:
; `reveal` expected Secret for argument 1, got String 

lazy

Creates a lazy value from a block. The block will only be evaluated when forced with _!.

Args: 1

block Block to evaluate lazily

returns LazyValue object that evaluates its block when forced

lazy { 1 + 2 } |type?
; returns lazyvalue

_! lazy { 1 + 2 }
; returns 3

l: lazy { 1 + 2 } , _! l , _! l
; returns 3

_!

Forces evaluation of a lazy value. If frozen evaluates the block and caches the result. If already thawed returns cached result.

Args: 1

value LazyValue to force

returns the evaluated and cached result

_! lazy { 1 + 2 }
; returns 3

l: lazy { 1 + 2 } , _! l , _! l
; returns 3

_>>

Converts first argument to a specific kind.

Args: 2

value Dict or context to convert

kind Kind object describing the target kind

returns converted context of the requested kind, or an error

raw-context

Creates a completely isolated context with no parent, where only built-in functions are available.

Args: 1

Types: 1 [ Block ]

block Block of expressions to evaluate in a new isolated context

returns context object with the values defined in the block

c: raw-context { x: 123 } c/x
; returns 123

y: 123 try { c: raw-context { x: y } } |type?
; returns error

try { c: raw-context { x: inc 10 } } |type?
; returns error

isolate

Creates a context that can access the parent context during creation, but becomes isolated afterward.

Args: 1

Types: 1 [ Block ]

block Block of expressions to evaluate in a temporary context

returns context object with the values defined in the block, but isolated from parent contexts

c: isolate { x: 123 } c/x
; returns 123

y: 123 c: isolate { x: y } c/x
; returns 123

c: isolate { x: inc 10 } c/x
; returns 11

context

Creates a new context from a block (evaluated), dict, or table row (converted).

Args: 1

Types: 1 [ Block Dict TableRow ]

arg Block of expressions to evaluate, or Dict or TableRow to convert to context

returns context object with the values defined in the block/dict/table row and access to parent context

c: context { x: 123 } c/x
; returns 123

y: 123 c: context { x: y } c/x
; returns 123

c: context { x: inc 10 } c/x
; returns 11

y: 123 c: context { x: does { y } } c/x
; returns 123

c: context { a: 1 b: 2 } c/a + c/b
; returns 3

c: context dict { "a" 1 "b" 2 } c/a + c/b
; returns 3

c: context first table { 'a 'b } { 1 2 } c/a + c/b
; returns 3

context\pure

Creates a new context using Pure Context (PCtx) as parent, preventing access to regular context changes.

Args: 1

Types: 1 [ Block ]

block Block of expressions to evaluate in a new pure context

returns context object with the values defined in the block, using Pure Context as parent

c: context\pure { x: 123 } c/x
; returns 123

c: context\pure { x: _+ 10 5 } c/x
; returns 15

private

Creates a temporary private context for evaluating expressions, returning the last value instead of the context.

Args: 1

Types: 1 [ Block ]

block Block of expressions to evaluate in a private context

returns the last value from evaluating the block (not the context itself)

private { x: 123 }
; returns 123

y: 123 private { x: y }
; returns 123

private { x: inc 10 }
; returns 11

y: 123 private { does { y } } :f f
; returns 123

private\

Creates a documented private context for evaluating expressions, returning the last value instead of the context.

Args: 2

Types: 1 [ String ] 2 [ Block ]

doc String containing documentation for the context

block Block of expressions to evaluate in a private context

returns the last value from evaluating the block (not the context itself)

private\ "what are we doing here" { x: 234 1000 + x }
; returns 1234

extends

Creates a new context that inherits from a specified parent context.

Args: 2

Types: 1 [ Context ] 2 [ Block ]

parent Context object to extend

block Block of expressions to evaluate in the new context

returns new context object that inherits from the parent context

ct: context { p: 123 } cn: extends ct { r: p + 234 } cn/r
; returns 357

bind!

Binds a context as a parent context to first context.

Args: 2

Types: 1 [ Context ] 2 [ Context ]

child Context object to be bound

parent Context object to bind to as parent

returns the modified child context with its parent set to the specified parent context

c: context { y: 123 } cc: bind! context { z: does { y + 234 } } c , cc/z
; returns 357

bind

Creates a clone of the first context and binds the second context as its parent.

Args: 2

Types: 1 [ Context ] 2 [ Context ]

child Context object to clone and bind

parent Context object to bind to as parent

returns a cloned child context with its parent set to the specified parent context

c: context { x: 123 } p: context { y: 456 } cc: bind c p cc/x
; returns 123

c: context { x: 123 } p: context { y: 456 } cc: bind c p cc/y
; returns 456

c: context { x:: 123 } p: context { y:: 456 } cc: bind c p do\inside c { x:: 999 } cc/x
; returns 123

c: context { x:: 123 } p: context { y:: 456 } cc: bind c p do\inside c { x:: 999 } c/x
; returns 999

anchor

Creates a clone of a context and sets current context as its parent.

Args: 1

Types: 1 [ Context ]

ctx Context object to clone and anchor to current context

returns a cloned context with current context set as parent

c: context { x: 123 } cc: anchor c cc/x
; returns 123

c: context { x:: 123 } cc: anchor c do\inside c { x:: 999 } cc/x
; returns 123

c: context { x:: 123 } cc: anchor c do\inside c { x:: 999 } c/x
; returns 999

anchor!

Sets current context as parent of the given context (modifies the context in place).

Args: 1

Types: 1 [ Context ]

ctx Context object to anchor to current context

returns the modified context with current context set as parent

c: context { x: 123 } anchor! c c/x
; returns 123

c: context { x:: 123 } anchor! c do\inside c { x:: 999 } c/x
; returns 999

unbind

Removes the parent relationship from a context, making it a standalone context.

Args: 1

Types: 1 [ Context ]

ctx Context object to unbind from its parent

returns the modified context with no parent

c: context { y: 123 } cc: bind! context { x: 234 z: does { x } } c , unbind cc cc/z
; returns 234

c: context { y: 123 } cc: bind! context { z: does { y } } c , dd: unbind cc dd/z
; correctly causes error:
; Word not found: `y`. 

whereis

Searches for a word in current context and its parents, returns block with [ depth context ] where word was found.

Args: 1

Types: 1 [ Word ]

word Word to look up in current or parent contexts

returns block with [ depth context ] where depth is the number of parent hops (0 = current context) and context is where the word was found

x: 123 whereis 'x |first
; returns 0

x: 123 c: context { y: 456 } do\in c { whereis 'x } |first
; returns 0

x: 123 c: context { y: 456 } do\in c { whereis 'y } |first
; returns 1

get

Gets the value of a word from current or parent contexts without calling it (similar to get-word ?word).

Args: 1

Types: 1 [ Word ]

word Word to look up in current or parent contexts

returns the value bound to the word (including functions without calling them)

x: 123 get 'x
; returns 123

f: does { 101 } get 'f |type?
; returns function

c: context { y: 456 } do\in c { get 'y }
; returns 456

current

Returns current context.

no arguments

returns the current context object

c: context { var 'x 9999 , incr: fn\inside { } current { x:: inc x } } c/incr c/x
; returns 10000

parent

Returns parent context of the current context.

no arguments

returns the parent context object, or an error when there is no parent

c: context { } do\inside c { parent |type? }
; returns context

parent?

Returns parent context of the current context.

no arguments

returns the parent context object, or an error when there is no parent

var 'y 99 c: context { incr: fn\inside { } parent? { y:: inc y } } c/incr y
; returns 100

parent\of

Returns parent context of the current context.

Args: 1

Types: 1 [ Context ]

context Context whose parent should be returned.

returns the parent Context.

ct: context { p: 123 } parent\of ct |= current
; returns true

lc

Lists words in current context

no arguments

returns current context after printing the list of words to stdout

lc

lc\data

Returns words in current context as a block.

no arguments

returns block of words defined in the current context

x: 123 lc\data |type?
; returns block

lc\data\

Returns words in specified context as a block.

Args: 1

Types: 1 [ Context ]

ctx Context to list words from

returns block of words defined in the specified context

c: context { x: 123 } lc\data\ c |type?
; returns block

lcp

Lists words in parent context

no arguments

returns current context after printing the parent context's words to stdout

lcp

lc\

Lists words in current context with string filter, by type (word: 'function, 'builtin, 'context), or regex filter (native of kind 'regex)

Args: 1

Types: 1 [ String Word Native ]

filter String to filter by name, Word ('function, 'builtin, 'context) to filter by type, or regex Native

returns current context after printing filtered words to stdout

lc\ "print"
lc\ 'function

lcp\

Lists words in parent context with string filter

Args: 1

Types: 1 [ String ]

filter String to filter word names

returns current context after printing filtered parent context words to stdout

lcp\ "print"

cc

Change to context (pushes current context to stack for ccb)

Args: 1

Types: 1 [ Context ]

ctx Context to change to

returns the new current context

cc my-context

ccp

Change to parent context (pushes current context to stack for ccb)

no arguments

returns the parent context (now current)

ccp

ccb

Change context back (pops from context stack)

no arguments

returns the previous context (now current)

ccb

mkcc

Make context with current as parent and change to it (pushes current context to stack for ccb).

Args: 1

Types: 1 [ Word ]

word Word to name the new context

returns the new context (now current)

mkcc 'my-sub-context

cc-stack-size

Returns the current size of the context navigation stack.

no arguments

returns Integer with the current size of the context navigation stack

cc-stack-size >= 0
; returns true

cc-stack-size

cc-clear-stack

Clears the context navigation stack (removes all stored previous contexts).

no arguments

returns Integer with the previous size of the stack before clearing

cc-clear-stack >= 0
; returns true

cc-clear-stack

clone

Creates a copy of a context with the same state and parent relationship.

Args: 1

Types: 1 [ Context ]

ctx Context object to clone

returns a new context object that is a copy of the original context

c: context { x: 123 y: 456 } cc: clone c cc/x
; returns 123

c: context { x: 123 y: 456 } cc: clone c cc/y
; returns 456

c: context { x:: 123 } cc: clone c do\inside cc { x:: 999 } c/x
; returns 123

c: context { x:: 123 } cc: clone c do\inside cc { x:: 999 } cc/x
; returns 999

clone\

Creates a copy of a context and evaluates a block of code inside the clone.

Args: 2

Types: 1 [ Context ] 2 [ Block ]

ctx Context object to clone

block Block of expressions to evaluate in the cloned context

returns the cloned context with the block evaluated inside it

c: context { x: 123 } cc: clone\ c { y: x + 100 } cc/y
; returns 223

c: context { x:: 123 } cc: clone\ c { x:: 999 } c/x
; returns 123

c: context { x:: 123 } cc: clone\ c { x:: 999 } cc/x
; returns 999

clone\deep

Creates a deep copy of a context with the same state and parent relationship, recursively copying all nested objects.

Args: 1

Types: 1 [ Context ]

ctx Context object to deep clone

returns a new context object that is a deep copy of the original context (including nested objects)

c: context { x: [ 1 2 3 ] } cc: clone\deep c cc/x
; returns { 1 2 3 }

c: context { x: [ 1 2 3 ] } cc: clone\deep c do\in cc { change\nth! ref x 1 999 } c/x -> 0
; returns 1

c: context { x: [ 1 2 3 ] } cc: clone\deep c do\in cc { change\nth! ref x 1 999 } cc/x -> 0
; returns 999

call-depth?

Returns the current function call depth as an integer (0 = top-level, 1 = inside one function call, etc.).

(none)

returns current function call depth as integer (0 = top-level, 1 = inside one function, etc.)

var 'd0 call-depth? , f: fn { } { call-depth? } , f - d0
; returns 1

max-call-depth!

Sets the maximum allowed function call depth (recursion limit). Use 0 for unlimited (default). Returns the previous limit. Calls that exceed this depth raise a stack-overflow error.

Args: 1

Types: 1 [ Integer ]

limit integer - new maximum call depth (0 = unlimited)

returns the previous MaxCallDepth value (0 = was unlimited)

max-call-depth! 10 , max-call-depth! 0
; returns 10

max-call-depth?

Returns the current maximum call depth limit as an integer (0 = unlimited).

(none)

returns current MaxCallDepth limit as integer (0 = unlimited)

max-call-depth?
; returns 0

max-call-depth! 50 max-call-depth?
; returns 50

ops-done?

Returns the number of expression evaluations counted since the last reset. The counter only advances while a MaxOps limit is enabled, so it is 0 by default.

(none)

returns number of expression evaluations counted since the last reset; 0 when MaxOps is unlimited

max-ops! 100 , do { 1 2 3 } , var 'c ops-done? , reset-ops , c > 0
; returns true

max-ops!

Sets the maximum number of expression evaluations allowed. Use 0 for unlimited (default). Returns the previous limit. Exceeding the limit raises an evaluation-limit error.

Args: 1

Types: 1 [ Integer ]

limit integer - new maximum number of expression evaluations (0 = unlimited)

returns the previous MaxOps value (0 = was unlimited)

max-ops! 100000 , max-ops! 0
; returns 100000

max-ops?

Returns the current maximum ops limit as an integer (0 = unlimited).

(none)

returns current MaxOps limit as integer (0 = unlimited)

max-ops?
; returns 0

max-ops! 50000 max-ops?
; returns 50000

reset-ops

Resets the OpsCount counter to zero and clears the MaxOps limit. Returns the OpsCount value before reset. Useful for re-arming the budget inside a fresh computation phase.

(none)

returns the OpsCount value before reset

max-ops! 100 reset-ops max-ops?
; returns 0

enter

Combines with and do\in: takes a value to inject, a context as parent, and a block to evaluate with both.

Args: 3

Types: 2 [ Context ] 3 [ Block ]

value Value to inject into the block (like with)

context Context to use as parent context during execution (like do\in)

block Block of code to execute with both the injected value and specified parent context

returns result of executing the block with both the injected value and modified parent context

c: context { x: 100 } , 123 |enter c { + x }
; returns 223

pipes: context { echo: { .print } into-file: { .print } } 123 |enter pipes { .echo .into-file data.txt }
; returns data.txt

if

Executes a block of code only if the condition is true, returning the result of the block or false.

Args: 2

Types: 1 [ Boolean ] 2 [ Block ]

condition Boolean value determining whether to execute the block

block Block of code to execute if condition is true

returns result of the block if condition is true, false otherwise

if true { 222 }
; returns 222

if false { 333 }
; returns false

if 1 { 222 }
; correctly causes error:
; `if` expected Boolean for argument 1 

if 0 { 333 }
; correctly causes error:
; `if` expected Boolean for argument 1 

when

Conditionally executes an action block if a condition block evaluates to true, injecting the same value into both blocks and returning the value of the action block if the condition is truthy or the original value otherwise.

Args: 3

Types: 2 [ Block ] 3 [ Block ]

value Value to inject into both condition and action blocks

condition Block that evaluates to a truthy/falsy value with the injected value

action Block to execute if condition is truthy, with the injected value

returns the value of the evaluated action block if condition is truthy or the original injected value if condition is falsy

10 .when { > 5 } { + 3 }
; returns 13

10 .when { < 5 } { + 3 }
; returns 10

^when

Conditionally executes an action block if a condition block evaluates to true, injecting the same value into both blocks and returning the value of the action block if the condition is truthy or the original value otherwise.

Args: 3

Types: 2 [ Block ] 3 [ Block ]

value Value to inject into both condition and action blocks

condition Block that evaluates to a truthy/falsy value with the injected value

action Block to execute if condition is truthy, with the injected value

returns the value of the evaluated action block if condition is truthy or the original injected value if condition is falsy

10 .when { > 5 } { + 3 }
; returns 13

10 .when { < 5 } { + 3 }
; returns 10

whether

Evaluates a condition block with the injected value and executes either the true or false block accordingly, returning the result. Like when with an else branch.

Args: 4

Types: 2 [ Block ] 3 [ Block ] 4 [ Block ]

value Value to inject into the condition block and the chosen action block

condition Block that evaluates to a truthy/falsy value with the injected value

true-block Block to execute if condition is truthy, with the value injected

false-block Block to execute if condition is falsy, with the value injected

returns result of the true-block if condition is truthy, result of the false-block otherwise

10 .whether { > 5 } { + 3 } { - 3 }
; returns 13

2 .whether { > 5 } { + 3 } { - 3 }
; returns -1

10 .whether { > 5 } { "big" } { "small" }
; returns "big"

2 .whether { > 5 } { "big" } { "small" }
; returns "small"

^if

Conditional that sets the return flag when true, allowing early return from a function when the condition is a boolean.

Args: 2

Types: 1 [ Boolean ] 2 [ Block ]

condition Value to evaluate for truthiness

block Block of code to execute and return from if condition is truthy

returns result of the block if condition is truthy (with return flag set), 0 otherwise

x: does { ^if true { 222 } 555 } x
; returns 222

x: does { ^if false { 333 } 444 } x
; returns 444

either

Executes one of two blocks based on a boolean condition, similar to if/else in other languages.

Args: 3

Types: 1 [ Boolean ] 3 [ Block ]

condition Boolean value determining which block to execute

true_block Block or value to return if condition is true

false_block Block or value to return if condition is false

returns result of executing the true_block if condition is true, otherwise result of false_block

either true { 222 } { 333 }
; returns 222

either false { 222 } { 333 }
; returns 333

either 5 > 3 { "yes" } { "no" }
; returns "yes"

either 1 { 222 } { 333 }
; correctly causes error:
; `either` expected Boolean for argument 1 

either 0 { 222 } { 333 }
; correctly causes error:
; `either` expected Boolean for argument 1 

choose

Returns the first or second value from a block of two values based on a boolean condition.

Args: 2

Types: 1 [ Boolean ] 2 [ Block ]

condition Boolean value determining which value to return

values Block containing exactly two values

returns first value if condition is true, second value if condition is false

choose true [ 1 -1 ]
; returns 1

choose false [ 1 -1 ]
; returns -1

choose 10 > 5 [ "yes" "no" ]
; returns "yes"

choose 3 < 2 [ "yes" "no" ]
; returns "no"

choose 1 [ 1 -1 ]
; correctly causes error:
; `choose` expected Boolean for argument 1 

choose true [ 1 ]
; correctly causes error:
; `choose`: Block must contain exactly 2 values. 

switch

Pattern matching construct that executes a block of code corresponding to the first matching case value.

Args: 2

Types: 2 [ Block ]

value Value to match against case values

cases Block containing case values and corresponding handler blocks

returns result of executing the matching handler block, or the original value if no match

switch 101 { 101 { 111 } 202 { 222 } }
; returns 111

switch 202 { 101 { 111 } 202 { 222 } }
; returns 222

cases

Evaluates multiple condition-action pairs and applies all matching actions cumulatively to the initial value.

Args: 2

Types: 2 [ Block ]

initial Initial value to be transformed by matching case blocks

cases Block containing condition blocks and corresponding transformation blocks

returns cumulative result after applying all matching transformation blocks to the initial value

cases 0 { { 1 > 0 } { + 100 } { 2 > 1 } { + 1000 } }
; returns 1100

cases 0 { { 1 > 0 } { + 100 } { 2 < 1 } { + 1000 } }
; returns 100

cases 0 { { 1 < 0 } { + 100 } { 2 > 1 } { + 1000 } }
; returns 1000

cases 0 { { 1 < 0 } { + 100 } { 2 < 1 } { + 1000 } }
; returns 0

cases 1 { { 1 > 0 } { + 100 } { 2 < 1 } { + 1000 } _ { * 3 } }
; returns 101

cases 1 { { 1 < 0 } { + 100 } { 2 > 1 } { + 1000 } _ { * 3 } }
; returns 1001

cases 1 { { 1 < 0 } { + 100 } { 2 < 1 } { + 1000 } _ { * 3 } }
; returns 3

loop

Executes a block of code, builtin, or function a specified number of times, injecting the current iteration number (starting from 1).

Args: 2

Types: 1 [ Integer ] 2 [ Block Builtin Function ]

count Integer number of iterations to perform

block Block of code to execute on each iteration

returns result of the last block execution

3 .loop {  "x" }
; prints "x x x "

3 .loop {  1 }
; returns 3

produce

Executes a block of code a specified number of times, passing the result of each execution to the next iteration.

Args: 3

Types: 1 [ Integer ] 3 [ Block ]

count Integer number of iterations to perform

initial Initial value to inject into the first block execution

block Block of code to execute on each iteration

returns result of the last block execution

produce 5 0 {  3 }
; returns 15

produce 3 ">" {  "x>" }
; returns ">x>x>x>"

produce 3 { } {  "x" }
; returns { "x" "x" "x" }

produce 3 { } { :x   x }
; returns { 0 1 2 }

produce 5 { 2 } { :acc  :x  x  acc }
; returns { 2 4 16 256 65536 4294967296 }

replicate

Executes a block of code a specified number of times and collects all results into a block.

Args: 2

Types: 1 [ Integer ] 2 [ Block ]

count Integer number of times to execute the block

block Block of code to execute on each iteration

returns Block containing the results of each execution

replicate 5 { 10 }
; returns { 10 10 10 10 10 }

replicate 3 { 1  2 }
; returns { 3 3 3 }

replicate 0 { 10 }
; returns { }

replicate\idx

Executes a block of code a specified number of times, injecting the current index (0-based), and collects all results into a block.

Args: 2

Types: 1 [ Integer ] 2 [ Block ]

count Integer number of times to execute the block

block Block of code to execute on each iteration, with index (0-based) injected

returns Block containing the results of each execution

replicate\idx 5 {  0 }
; returns { 0 1 2 3 4 }

replicate\idx 3 {  10 }
; returns { 0 10 20 }

replicate\idx 0 { 10 }
; returns { }

produce\while

Executes a block of code repeatedly while a condition is true, passing the result of each execution to the next iteration.

Args: 3

Types: 1 [ Integer ] 3 [ Block ]

condition Block that evaluates to a boolean to determine when to stop iterating

initial Initial value to inject into the first block execution

block Block of code to execute on each iteration

returns result of the last block execution before the condition became false

var 'x 0 , produce\while { x  100 } 1 {  2 :x }
; returns 64

var 'x 0 , produce\while { x  100 } 1 {  2 :x  }
; prints "2 4 8 16 32 64 128 "

produce\

Executes a block of code a specified number of times, updating an accumulator word with each iteration result.

Args: 4

Types: 1 [ Integer ] 3 [ Word ] 4 [ Block ]

count Integer number of iterations to perform

initial Initial value for the accumulator

accumulator Word to store the accumulator value

block Block of code to execute on each iteration

returns final value of the accumulator word after all iterations

produce\ 5 1 'acc {  acc ,  1 }
; returns 1

forever

Executes a block of code repeatedly until .return is called within the block.

Args: 1

Types: 1 [ Block ]

block Block of code to execute repeatedly

returns result of the block when .return is called

forever { "once"   }
; prints "once"

forever { "once"  }
; returns "once"

forever\with

Accepts a value and a block, and executes the block repeatedly with the value until .return is called.

Args: 2

Types: 1 [ Block ]

value Value to inject into the block on each iteration

block Block of code to execute repeatedly

returns result of the block when .return is called

forever\with 1 {   }
; prints "1"

var 'x 0 , forever\with 1 {  5 :x ,  x  5 { return x } }
; returns 6

for

Accepts a block of values and a block of code, builtin, or function, does the code for each of the values, injecting them.

Args: 2

Types: 1 [ String Block Table ] 2 [ Block Builtin Function ]

collection Collection (Block, List, String, or Table) to iterate over

code Block, Builtin, or Function to execute for each value, injecting the value

returns result of the last code execution

for { 1 2 3 } {  "x" }
; prints "x x x "

{ "a" "b" "c" } .for {  }
; prints "a b c "

for\pos

Iterates over a collection with position tracking (1-based), setting a word to the current position and injecting each value.

Args: 3

Types: 1 [ Block List String ] 2 [ Word ] 3 [ Block ]

collection Collection to iterate over

word Word to store the current position (1-based index)

code Block of code to execute for each value

returns result of the last block execution

{ "a" "b" "c" } .for\pos 'i { i  ,  }
; prints "1 a 2 b 3 c "

for\idx

Iterates over a collection with index tracking (0-based), setting a word to the current index and injecting each value.

Args: 3

Types: 1 [ Block List String ] 2 [ Word ] 3 [ Block ]

collection Collection to iterate over

word Word to store the current index (0-based)

code Block of code to execute for each value

returns result of the last block execution

{ "a" "b" "c" } .for\idx 'i { i  ,  }
; prints "0 a 1 b 2 c "

walk

Walks through a block, executing code that can modify the block on each iteration (useful for custom iteration patterns).

Args: 2

Types: 1 [ Block ] 2 [ Block ]

block Block to walk through

code Block of code to execute, which should return a modified block

returns result of the last block execution

walk { 1 2 3 } {   }
; prints "1 2 3 2 3 3 "

var 'x 0 , walk { 1 2 3 } { :b   x :x , b  } x
; returns 6

walk\pos

Walks through a block with position tracking (1-based), setting a word to the current position and executing code that can modify the block.

Args: 3

Types: 1 [ Block ] 2 [ Word ] 3 [ Block ]

block Block to walk through

word Word to store the current position (1-based index)

code Block of code to execute, which should return a modified block

returns result of the last block execution

walk\idx

Walks through a block with index tracking (0-based), setting a word to the current index and executing code that can modify the block.

Args: 3

Types: 1 [ Block ] 2 [ Word ] 3 [ Block ]

block Block to walk through

word Word to store the current index (0-based)

code Block of code to execute, which should return a modified block

returns result of the last block execution

walk\idx { 1 2 3 } 'i {  , i  ,  }
; prints "1 2 3 0 2 3 1 3 2 "

purge

Purges values from a series based on return of a injected code block.

Args: 2

Types: 1 [ Block List String Table ] 2 [ Block ]

series Block, List, String, or Table to purge from

code Block of code that returns true for values to remove

returns modified series with matching values removed

purge { 1 3 3 } {  }
; returns { 1 3 }

purge { } {  }
; returns { }

purge list { 1 2 3 } {  }
; returns list { 1 3 }

purge list { } {  }
; returns list { }

purge "1234" {    }
; returns { "1" "3" }

purge "" {   }
; returns { }

purge!

Purges values from a block stored in a word (modifying it in-place), returning the purged values.

Args: 2

Types: 1 [ Block ] 2 [ Word ]

code Block of code that returns true for values to remove

word Word referring to a Block to purge from (modified in-place)

returns Block containing the purged values

{ 1 3 3 } :x purge! {  } 'x , x
; returns { 1 3 }

map

Maps values of a block to a new block by evaluating a block of code or function.

Args: 2

Types: 1 [ Block List String ] 2 [ Block Builtin Function ]

collection Block, List, or String to map over.

function Block, function, or builtin applied to each item.

returns a Block or List with the mapped values.

map { 1 2 3 } {  1 }
; returns { 2 3 4 }

map { } {  1 }
; returns { }

map { "aaa" "bb" "c" } {  }
; returns { 3 2 1 }

map list { "aaa" "bb" "c" } {  }
; returns list { 3 2 1 }

map list { 3 4 5 6 } {  3 }
; returns list { true false false true }

map list { } {  1 }
; returns list { }

map "123" {  }
; returns { 1 2 3 }

map "123" ?integer
; returns { 1 2 3 }

map "" {  "-" }
; returns { }

map\pos

Maps values of a block to a new block by evaluating a block of code.

Args: 3

Types: 1 [ Block List String ] 2 [ Word ] 3 [ Block ]

collection Block, List, or String to map over.

index-word Word bound to the 1-based position.

function Block applied to each item with the position bound.

returns a Block or List with the mapped values.

map\pos { 1 2 3 } 'i {  i }
; returns { 2 4 6 }

map\pos { } 'i { + i }
; returns { }

map\pos list { 1 2 3 } 'i {  i }
; returns list { 2 4 6 }

map\pos list { } 'i { + i }
; returns list { }

map\pos "abc" 'i {  i }
; returns { "a1" "b2" "c3" }

map\pos "" 'i { + i }
; returns { }

map\idx

Maps values of a block to a new block by evaluating a block of code.

Args: 3

Types: 1 [ Block List String ] 2 [ Word ] 3 [ Block ]

collection Block, List, or String to map over.

index-word Word bound to the 0-based index.

function Block applied to each item with the index bound.

returns a Block or List with the mapped values.

map\idx { 1 2 3 } 'i {  i }
; returns { 1 3 5 }

map\idx { } 'i { + i }
; returns { }

map\idx list { 1 2 3 } 'i {  i }
; returns list { 1 3 5 }

map\idx list { } 'i { + i }
; returns list { }

map\idx "abc" 'i {  i }
; returns { "a0" "b1" "c2" }

map\idx "" 'i { + i }
; returns { }

reduce

Reduces values of a block to a single value by evaluating a block of code, using the first element as the initial accumulator.

Args: 3

Types: 1 [ Block List String ] 2 [ Word ] 3 [ Block ]

collection Collection to reduce (must not be empty)

accumulator Word to store the accumulator value

code Block of code to execute for each value, receiving accumulator as context

returns final accumulated value

reduce { 1 2 3 } 'acc {  acc }
; returns 6

reduce list { 1 2 3 } 'acc {  acc }
; returns 6

reduce "abc" 'acc {  acc }
; returns "cba"

try { reduce { } 'acc { + acc } } |type?
; returns error

try { reduce list { } 'acc { + acc } } |type?
; returns error

try { reduce "" 'acc { + acc } } |type?
; returns error

reduce { 1 2 3 4 } 'acc {  acc }
; returns 24

fold\do

Reduces values of a block to a new block by evaluating a block of code ...

Args: 4

Types: 1 [ Block List String ] 2 [ Word ] 4 [ Block ]

collection Block, List, or String to fold.

accumulator-word Word bound to the accumulator.

initial Initial accumulator value.

function Block evaluated for each item.

returns the final accumulator value.

fold\do { 1 2 3 } 'acc 1 {  acc }
; returns 7

fold\do { } 'acc 1 { + acc }
; returns 1

fold\do list { 1 2 3 } 'acc 1 {  acc }
; returns 7

fold\do list { } 'acc 1 { + acc }
; returns 1

fold\do "abc" 'acc "123" {  acc }
; returns "cba123"

fold\do "" 'acc "123" { + acc }
; returns "123"

fold

Reduces values of a block to a new block by evaluating a block of code ...

Args: 3

Types: 1 [ Block List String ] 4 [ Function ]

collection Block, List, or String to fold.

initial Initial accumulator value.

function Function receiving (value accumulator) for each item.

returns the final accumulator value.

fold { 1 2 3 } 1 fn { v acc } { + acc }
; returns 7

fold { } 1 fn { v acc } { + acc }
; returns 1

fold list { 1 2 3 } 1 fn { v acc } { v + acc }
; returns 7

fold { "a" "b" "c" } "" fn { v acc } { acc .concat v }
; returns "abc"

partition

Partitions a series by evaluating a block of code, grouping consecutive elements that return the same result.

Args: 2

Types: 1 [ Block List String ] 2 [ Block Builtin ]

series String, Block, or List to partition

code Block or Builtin that returns a value for grouping consecutive elements

returns collection of partitions (each partition contains consecutive elements with the same result)

partition { 1 2 3 4 } {  2 }
; returns { { 1 2 } { 3 4 } }

partition { "a" "b" 1 "c" "d" } {  }
; returns { { "a" "b" } { 1 } { "c" "d" } }

partition { "a" "b" 1 "c" "d" } ?is-integer
; returns { { "a" "b" } { 1 } { "c" "d" } }

partition { } {  2 }
; returns { { } }

partition list { 1 2 3 4 } {  2 }
; returns list { list { 1 2 } list { 3 4 } }

partition list { "a" "b" 1 "c" "d" } ?is-integer
; returns list { list { "a" "b" } list { 1 } list { "c" "d" } }

partition list { } {  2 }
; returns list { list { } }

partition "aaabbccc" { , }
; returns list { "aaa" "bb" "ccc" }

partition "" { , }
; returns list { "" }

partition "aaabbccc" ?is-string
; returns list { "aaabbccc" }

group

Groups a block or list of values by a key generated from a code block (keys must be strings).

Args: 2

Types: 1 [ Block List ] 2 [ Block Builtin ]

series Block or List to group

code Block or Builtin that returns a string key for grouping

returns Dict with string keys and List values containing grouped elements

{ } .list .group {  }
; returns dict { }

try { { 1 2 3 4 } .group {  } } |type?
; returns error

filter

Filters values from a seris based on return of a injected code block.

Args: 2

Types: 1 [ Block List String ] 2 [ Block Builtin ]

collection Block, List, or String to filter.

predicate Block, function, or builtin returning truthy for kept items.

returns a collection of the same kind containing matching items.

filter { 1 2 3 4 } {  }
; returns { 2 4 }

filter { 1 2 3 4 } ?is-even
; returns { 2 4 }

filter { } {  }
; returns { }

filter list { 1 2 3 4 } {  }
; returns list { 2 4 }

filter list { 1 2 3 4 } ?is-even
; returns list { 2 4 }

filter { 1 3 5 7 } {  }
; returns { }

seek

Seek over a series until a Block of code, Builtin, or Function returns True and return the value.

Args: 2

Types: 1 [ Block List String ] 2 [ Block Builtin Function ]

series Block, List, or String to search through

code Block, Builtin, or Function that returns true when the desired value is found

returns first value for which the code returns true, error if none found

seek { 1 2 3 4 } {  }
; returns 2

seek list { 1 2 3 4 } {  }
; returns 2

seek "1234" {   }
; returns "2"

try { seek { 1 2 3 4 } {  5 } } |type?
; returns error

try { seek list { 1 2 3 4 } {  5 } } |type?
; returns error

try { seek "1234" {   5 } } |type?
; returns error

seek { 1 2 3 4 } ?is-even
; returns 2

seek list { 1 2 3 4 } ?is-even
; returns 2

my-is-even: fn { x } { x .is-even } , seek { 1 2 3 4 } ?my-is-even
; returns 2

while

Executes a block of code repeatedly while a condition is true.

Args: 2

Types: 1 [ Block ] 2 [ Block ]

condition Block that evaluates to a boolean to determine whether to continue

body Block of code to execute repeatedly

returns result of the last body execution

var 'x 0 while { x  5 } { x:: x  1 } x
; returns 5

var 'x 0 var 'y 0 while { x  5 } { x:: x  1 y:: y  x } y
; returns 15

until

Executes a block of code repeatedly until a condition becomes true. Executes the body at least once before checking condition (do-until loop).

Args: 2

Types: 1 [ Block ] 2 [ Block ]

body Block of code to execute repeatedly (executed at least once)

condition Block that evaluates to a boolean to determine when to stop

returns result of the last body execution

var 'x 5 until { x  0 } { x:: x  1 } x
; returns 0

var 'x 10 var 'y 0 until { x  5 } { x:: x  1 y:: y  x } y
; returns 35

var 'x 3 until { x  1 } { x:: x  1 } x
; returns 0

var 'x 0 until { x  0 } { x:: x  1 } x
; returns 1

for\

Iterates over a collection, setting a word to each value. Works with lists, blocks, and strings.

Args: 3

Types: 1 [ Block List String ] 2 [ Word ] 3 [ Block ]

collection String, Block, List, or other Collection to iterate over

word Word to store each value during iteration

block Block of code to execute for each value

returns result of the last block execution

{ 1 2 3 } .for\ 'x { x  }
; prints "1 2 3 "

list { 10 20 30 } |for\ 'val { val  }
; prints "10 20 30 "

"abc" .for\ 'ch { ch  }
; prints "a b c "

for\kv

Iterates over a collection with separate key and value words. For dicts, uses actual keys and values. For other collections, uses indices as keys.

Args: 4

Types: 1 [ Dict Block List String ] 2 [ Word ] 3 [ Word ] 4 [ Block ]

collection Dict, Block, List, or other Collection to iterate over

keyWord Word to store the key (or index for non-dict collections)

valueWord Word to store the value

block Block of code to execute for each key-value pair

returns result of the last block execution

dict { "a" 1 } |for\kv 'k 'v { k  v  }
; prints "a 1 "

{ 10 20 30 } .for\kv 'i 'v { i  v  }
; prints "0 10 1 20 2 30 "

var

Declares a word as a variable with the given value, allowing it to be modified. Returns the word for use with on-change.

Args: 2

word Tagword representing the variable name

value Initial value for the variable

returns The initial value

var 'x 10 x:: 20 x
; returns 20

does

Creates a function with no arguments that executes the given block when called.

Args: 1

body Block containing the function body code

returns function object with no parameters

does { 123 } |type?
; returns function

x: does { 123 } x
; returns 123

x: does { 1 + 2 } x
; returns 3

fn1

Creates a function that accepts one anonymous argument and executes the given block with that argument.

Args: 1

body Block containing the function body code

returns function object that accepts one anonymous argument

fn1 { .pass { } } |type?
; returns function

x: fn1 { } , x 123
; returns 123

x: fn1 { .pass { } } , x 123
; returns 123

x: fn1 { + 1 } , x 123
; returns 124

fn

Creates a function with named parameters specified in the first block and code in the second block.

Args: 2

spec Block containing parameter specifications

body Block containing the function body code

returns function object with the specified parameters

fn { } { } |type?
; returns function

x: fn { } { 234 } , x
; returns 234

x: fn { x } { x } , x 123
; returns 123

x: fn { x } { + 123 } , x 123
; returns 246

add: fn { a b } { a + b } , add 10 20
; returns 30

fn\dyn

Creates a function whose free words resolve through the caller's context (dynamic scoping).

Args: 2

spec Block containing parameter specifications

body Block containing the function body code

returns function object whose free words resolve dynamically through the caller's context

f: fn\dyn { x } { x + 1 } , f 2
; returns 3

f: fn\dyn { x } { x + 1 } |type?
; returns function

fn\spec?

Returns the argument specification block of a function.

Args: 1

function Function to get the argument spec from

returns Block containing the function's parameter specification

f: fn { x y } { x + y } , ?f .fn\spec?
; returns { x y }

does { 1 } |fn\spec?
; returns { }

fn\body?

Returns the body block of a function.

Args: 1

function Function to get the body from

returns Block containing the function's body code

f: fn { x y } { x + y } , ?f .fn\body?
; returns { x + y }

does { 123 } |fn\body?
; returns { 123 }

pfn

Creates a pure function (no side effects allowed) with named parameters and code body.

Args: 2

spec Block containing parameter specifications

body Block containing the function body code

returns pure function object with the specified parameters

pfn { } { } |type?
; returns function

x: pfn { x } { + 123 } , x 123
; returns 246

fn\cc

Creates a function that captures the current context, allowing access to variables from the enclosing scope.

Args: 2

Types: 1 [ Block ] 2 [ Block ]

spec Block containing parameter specifications

body Block containing the function body code

returns function object with the current context captured

fn\cc { x } { x + y } |type?
; returns function

y: 5 , f: fn\cc { x } { x + y } , f 3
; returns 8

fn\in

Creates a function with a specified parent context, allowing access to variables from that context.

Args: 3

Types: 1 [ Block ] 2 [ Context ] 3 [ Block ]

spec Block containing parameter specifications

context Context object to use as parent context

body Block containing the function body code

returns function object with the specified parent context

ctx: context { y: 5 } , f: fn\in { x } ctx { x + y } , f 3
; returns 8

fn\inside

Creates a function that executes directly in the specified context rather than creating a new execution context.

Args: 3

Types: 1 [ Block ] 2 [ Context ] 3 [ Block ]

spec Block containing parameter specifications

context Context object to execute the function in

body Block containing the function body code

returns function object that executes directly in the specified context

ctx: context { y: 5 } , f: fn\inside { x } ctx { x + y } , f 3
; returns 8

modder

Creates a function that executes directly in the current context (like fn\inside with current), allowing arguments and context words to be modified with word::.

Args: 2

Types: 1 [ Block ] 2 [ Block ]

spec Block containing parameter specifications

body Block containing the function body code

returns function object that executes directly in the current context (captured at creation), with arguments as variables

var 'x 0 , inc: modder { } { x:: x + 1 } , inc , inc , x
; returns 2

var 'n 10 , add: modder { v } { n:: n + v } , add 5 , n
; returns 15

closure

Creates a closure that captures the current context at creation time, preserving access to variables in that scope.

Args: 2

Types: 1 [ Block ] 2 [ Block ]

spec Block containing parameter specifications

body Block containing the function body code

returns function object that captures the current context at creation time

y: 5 , f: closure { x } { x + y } , f 3
; returns 8

mk-cntr: does { var 'c 0 , closure { } { inc! 'c } } cnt: mk-cntr , cnt + cnt + cnt
; returns 6

partial

Creates a partially applied function with specified arguments, using _ (void) for arguments to be filled later.

Args: 2

Types: 1 [ Builtin Function ] 2 [ Block ]

func Function or builtin to partially apply

args Block of arguments, with _ (void) for arguments to be filled later

returns CurriedCaller object that can be called with the remaining arguments

prepend-star: partial ?concat [ "* " _ ] , prepend-star "hello"
; returns "* hello"

add-5: partial ?_+ [ _ 5 ] , add-5 10
; returns 15

fn-add: fn { x y } { x + y } , add-5: partial ?fn-add { _ 5 } , add-5 10
; returns 15

apply

Applies a function or builtin to a block of arguments.

Args: 2

Types: 1 [ Function Builtin VarBuiltin ] 2 [ Block ]

function Function or builtin to apply

args Block of arguments to pass to the function

returns The result of applying the function to the arguments

apply ?_+ { 12 23 }
; returns 35

apply fn { x y } { x + y } { 5 10 }
; returns 15

f: fn { x y } { x * y } , apply ?f { 7 6 }
; returns 42

on-change

Registers an observer block to be executed when a variable changes. Use with 'var' result.

Args: 2

Types: 1 [ Word ] 2 [ Block ]

word Word representing the variable to observe

observer Block containing code to execute when variable changes

returns The observer block

x: var 'counter 0 , on-change x { print "changed" } , counter:: 5
; returns 5

change!

Searches for a word and changes it's value in-place. Only works on variables declared with var. If value changes returns true otherwise false

Args: 2

Types: 1 [ Word ]

value New value to assign to the word

word Word whose value should be changed

returns Boolean true if the value changed, false if the new value is the same as the old value

var 'x 123 , change! 234 'x , x
; returns 234

a:: 123 change! 333 'a a
; returns 333

a:: 123 change! 124 'a
; returns true

a:: 123 change! 123 'a
; returns false

modify!

Searches for a word and modifies it's value in-place. Only works on variables declared with var. If value changes returns true otherwise false

Args: 2

Types: 1 [ Word ]

value New value to assign to the word

word Word whose value should be changed

returns Boolean true if the value changed, false if the new value is the same as the old value, will replace change!

var 'x 123 , modify! 234 'x , x
; returns 234

a:: 123 modify! 333 'a a
; returns 333

a:: 123 modify! 124 'a
; returns true

a:: 123 modify! 123 'a
; returns false

set

Set word to value or words by deconstructing a block. Only works on variables declared with var.

Args: 2

Types: 1 [ Block ] 2 [ Block ]

values Value or block of values to assign to the word(s)

words Word or block of words to be set

returns The value or block of values that was assigned

set { 123 234 } { a b } b
; returns 234

unset!

Unset a word in current context, only meant to be used in console

Args: 1

Types: 1 [ Word ]

word Word to be unset from the current context

returns Void value

x: 1 unset! 'x x: 2
; returns 2

val

Returns value of the word in context

Args: 1

Types: 1 [ Word ]

word Word whose value should be retrieved

returns The value associated with the word in the current context

x: 123 val 'x
; returns 123

x: 123 y: 'x val y
; returns 123

_<<

Converts a value to specific kind (R to L)

Args: 2

Types: 1 [ Kind ] 2 [ Dict Context ]

kind Kind to convert the value to

value Dict or context to convert

returns A new context of the specified kind

_|

Pipeline operator that passes the value through unchanged (used with 'not' and other operations).

Args: 1

value Any value to be passed through unchanged

returns the original value (used in pipeline operations for explicit pass-through)

5 ||
; returns 5

"hello" ||
; returns "hello"

true ||
; returns true

{ 1 2 3 } ||
; returns { 1 2 3 }

doc!

Sets docstring of the current context.

Args: 1

Types: 1 [ String ]

doc String to set as the docstring for the current context

returns Integer 1 on success

x: private { doc! "some doc" doc? }
; returns "some doc"

doc?

Gets docstring of the current context.

no arguments

returns String containing the docstring of the current context

x: private { doc! "some doc" doc? }
; returns "some doc"

doc\of?

Get docstring of the passed context.

Args: 1

Types: 1 [ Context PersistentContext ]

value Function, builtin, or context to get the docstring from

returns String containing the docstring of the provided value

x: context { doc! "some doc" } doc\of? x
; returns "some doc"

ref

Makes a value mutable instead of immutable

Args: 1

Types: 1 [ Table Dict List Block String Native Context ]

value Value to make mutable

returns A mutable reference to the value

is-ref ref { 1 2 3 }
; returns true

ref { 1 2 3 } |type?
; returns block

ref dict { "a" 1 } |type?
; returns dict

ref list { 1 2 3 } |type?
; returns list

ref "hello" |disarm |type?
; returns string

deref

Makes a value again immutable

Args: 1

Types: 1 [ Table Dict List Block String Native Context ]

value Mutable reference to make immutable

returns An immutable copy of the value

is-ref deref ref { 1 2 3 }
; returns false

deref ref { 1 2 3 }
; returns { 1 2 3 }

deref ref "hello"
; returns "hello"

deref ref list { 1 2 3 } |length?
; returns 3

ref dict { "a" 1 } |deref |type?
; returns dict

is-ref

Checks if a value is a mutable reference.

Args: 1

value Any value to check if it's a reference

returns Boolean true if the value is a reference, false otherwise

ref { } |is-ref
; returns true

{ } |is-ref
; returns false

ref "hello" |is-ref
; returns true

"hello" |is-ref
; returns false

ref list { 1 2 3 } |is-ref
; returns true

123 |is-ref
; returns false

is-same

Checks if two values are the same object (identity comparison, not value comparison).

Args: 2

value1 First value to compare

value2 Second value to compare

returns Boolean true if values are the same object (identity), false otherwise

a: ref [ 1 2 ] is-same a a
; returns true

a: ref [ 1 2 ] b: ref [ 1 2 ] is-same a b
; returns false

a: ref [ 1 2 ] b: a is-same a b
; returns true

is-same 123 123
; returns true

is-same "abc" ( string "ab" ++ "c" )
; returns false

dict

Constructs a Dict from the Block of key and value pairs, or converts a TableRow to a Dict.

Args: 1

Types: 1 [ Block TableRow ]

value Block containing alternating keys and values, or a TableRow to convert

returns A new Dict with the specified keys and values

dict { "a" 123 } |-> "a"
; returns 123

dict { "name" "John" "age" 30 } |-> "name"
; returns "John"

dict { } |type?
; returns dict

dict { "x" 1 "y" 2 "z" 3 } |length?
; returns 3

dict { 123 "value" }
; correctly causes error:
; `dict`: invalid key [Integer: 123] at position 0; keys must be strings, tagwords, words, or setwords 

dict { { } "value" }
; correctly causes error:
; `dict`: invalid key [Block: ] at position 0; keys must be strings, tagwords, words, or setwords 

dict { 'key "value" } |-> "key"
; returns "value"

dict first table { 'a 'b } { 1 2 } |-> "a"
; returns 1

dict first table { 'a 'b } { 1 2 } |type?
; returns dict

change

Returns a new Dict with the specified key changed to the new value. Original dict is unchanged.

Args: 3

Types: 1 [ Dict ] 2 [ String Word ]

dict Dict to update

key String key to change

value New value for the key

returns A new Dict with the key updated (original dict unchanged)

dict { "a" 1 "b" 2 } |change "a" 99 |-> "a"
; returns 99

dict { "a" 1 "b" 2 } |change "c" 3 |-> "c"
; returns 3

d: dict { "x" 10 } , change d "x" 20 |-> "x"
; returns 20

list

Constructs a List from the Block of values.

Args: 1

block Block containing values to put in the list

returns A new List with the values from the block

list { "a" 123 } |-> 0
; returns "a"

list { 1 2 3 } |length?
; returns 3

list { } |length?
; returns 0

list { "hello" "world" } |-> 1
; returns "world"

list { 1 2 3 } |type?
; returns list

list { 1 2 3 } |first
; returns 1

list { 1 2 3 } |last
; returns 3

load

Loads a string into Rye values.

Args: 1

Types: 1 [ String ]

source String containing Rye code to load

returns Block containing the parsed Rye values

load " 1 2 3 " |third
; returns 3

load "{ 1 2 3 }" |first |third
; returns 3

load\mod

Loads a string into Rye values. During load it allows modification of words.

Args: 1

Types: 1 [ String ]

source String containing Rye code or URI of file to load with modification allowed

returns Block containing the parsed Rye values

load\live

Loads a string into Rye values. During load it allows modification of words.

Args: 1

Types: 1 [ String ]

source String containing Rye code to load with modification allowed and file watching

returns Block containing the parsed Rye values

load\sig

Checks the signature, if OK then loads a string into Rye values.

Args: 1

source String containing signed Rye code to verify and load

returns Block containing the parsed Rye values if signature is valid

do

Takes a block of code and does (runs) it.

Args: 1

Types: 1 [ Block ]

block Block of code to execute

returns result of executing the block

do { 123 + 123 }
; returns 246

do { 123 + }
; correctly causes error:
; missing argument 2 

do { _+ _+ 12 23 34 }
; returns 69

do { 12 * 23 |+ 34 }
; returns 310

do { ( 12 * 23 ) + 34 }
; returns 310

do { 12 * 23 || + 34 }
; returns 310

do { 12 * 23 :a + 34 }
; returns 310

do { 12 * 23 :a a + 34 }
; returns 310

with

Takes a value and a block of code. It does the code with the value injected.

Args: 2

Types: 2 [ Block ]

value Value to inject into the block's execution context

block Block of code to execute with the injected value

returns result of executing the block with the injected value

with 100 { + 11 }
; returns 111

with 100 { + 11 , * 3 }
; returns 300

do\inside

Takes a Context and a Block. It Does a block inside a given Context.

Args: 2

Types: 1 [ Context PersistentContext ] 2 [ Block ]

context Context in which to execute the block

block Block of code to execute within the specified context

returns result of executing the block within the given context

c: context { x: 100 } do\inside c { x * 9.99 }
; returns 999

c: context { x:: 100 } do\inside c { inc! 'x }
; returns 101

c: context { var 'x 100 } do\inside c { x:: 200 } c/x
; returns 200

c: context { x:: 100 } do\inside c { x:: 200 , x }
; returns 200

do\in

Takes a Context and a Block. It Does a block in current context but with parent a given Context.

Args: 2

Types: 1 [ Context ] 2 [ Block ]

context Context to use as parent context during execution

block Block of code to execute in current context with the specified parent context

returns result of executing the block with the modified parent context

c: context { x: 100 } do\in c { x * 9.99 }
; returns 999

c: context { x:: 100 } do\in c { inc! 'x }
; returns 101

c: context { x: 100 } do\in c { x:: 200 , x }
; returns 200

c: context { x: 100 } do\in c { x:: 200 } c/x
; returns 100

do\inx

Takes a Context and a Block. It Does a block in current context but with parent a given Context.

Args: 2

Types: 1 [ Context ] 2 [ Block ]

context Context to use as parent context during execution

block Block of code to execute in current context with the specified parent context

returns result of executing the block with the modified parent context

c: context { x: 100 } do\in c { x * 9.99 }
; returns 999

c: context { x:: 100 } do\in c { inc! 'x }
; returns 101

c: context { x: 100 } do\in c { x:: 200 , x }
; returns 200

c: context { x: 100 } do\in c { x:: 200 } c/x
; returns 100

do\each

Evaluates each subblock of a block of subblocks, one at a time, and returns the result of the last subblock.

Args: 1

Types: 1 [ Block ]

blocks Block of subblocks to evaluate

returns result of evaluating the last subblock

do\each { { 1 + 2 } { 3 + 4 } }
; returns 7

do\each { { var 'x 10 , x + 1 } { x + 2 } }
; returns 12

lk\

Lists available kinds with string filter

Args: 1

Types: 1 [ String ]

prefix String used to filter kind names.

returns Void after printing the matching kinds.

lg\

Lists generic words related to specific kind with string filter

Args: 2

Types: 2 [ String ]

kind Word or value whose kind should be listed.

prefix String used to filter method names.

returns Void after printing the matching methods.

return

Accepts one value and returns it.

Args: 1

value Value to return from the current function.

returns the provided value.

x: fn { } { return 101 202 } x
; returns 101

rye

Returns the native Rye-itself object used to inspect and configure the running interpreter.

no arguments

returns native Rye-itself object used to access runtime properties.

rye .type?
; returns native

Rye-itself//On-error

Registers a On-error block that will be executed with the error injected if an unhandled error bubbles to the top of the program. The error value is injected as the first value (use .disarm, .print, etc.).

Args: 2

Types: 2 [ Block ]

rye-itself The rye native object (passed via dot-word dispatch)

block Block of code to execute with the On-errord error injected when an error bubbles to top-level

returns The rye-itself native (so the chain continues cleanly)

rye .On-error { .disarm .print } "ok"
; prints ""

defer

Registers a block of code to be executed when the current function exits or the program terminates.

Args: 1

Types: 1 [ Block ]

block Block to execute when the current function exits.

returns Void value.

x:: 123 defer { x:: 345 } x
; returns 123

ff:: fn { } { var 'x 123 defer { print 234 } x } , ff
; prints "234
; "

ff:: fn { } { x:: 123 defer { x:: 234 } x + 111 } , ff
; returns 234

defer\

Registers a block of code with an injected value to be executed when the current function exits or the program terminates. Works like 'with' but deferred.

Args: 2

Types: 2 [ Block ]

value Value to inject into the deferred block

block Block to execute with the injected value when function exits

returns Void value

x:: 0 defer\ 42 { + 1 } x
; returns 0

ff:: fn { } { defer\ "hello" { .print } "done" } , ff
; prints "hello
; "

assert

Evaluates a block of code and asserts that its result equals the expected value. Returns the result if assertion passes, fails with error message if not.

Args: 2

Types: 1 [ Block ]

block Block of code to evaluate

expected Expected result value

returns The result value if assertion passes, error if it fails

assert { 1 + 2 } 3
; returns 3

assert { "hello" } "hello"
; returns "hello"

assert { 1 + 2 } 5
; correctly causes error:
; Assertion failed: expected `[Integer: 5]` but got `[Integer: 3]` 

assert\display

Evaluates a block of code and displays the result. Prints the explanation in magenta followed by OK in green on success, or error message in red on failure. Does not fail - continues evaluation.

Args: 3

Types: 1 [ String ] 2 [ Block ]

explanation String describing the test being performed

block Block of code to evaluate

expected Expected result value

returns The result value (displays status but continues evaluation even on failure)

assert\display "check addition" { 1 + 2 } 3
; prints "check addition: OK
; "

recur-if

Internal recursion control function. Resets function execution if condition > 0, otherwise returns result.

Args: 2

Types: 1 [ Integer ]

condition Integer value, if > 0 triggers recursion reset

returns nil if recursion continues, ps.Res if recursion ends

recur-if\1

Internal recursion control function for single-argument functions. Updates first argument and resets if condition > 0.

Args: 2

Types: 1 [ Integer ] 2 [ Integer ]

condition Integer value, if > 0 triggers recursion with updated argument

arg1 New value for the first function argument during recursion

returns nil if recursion continues, ps.Res if recursion ends

recur-if\2

Internal recursion control function for two-argument functions. Updates both arguments and resets if condition > 0.

Args: 3

Types: 1 [ Integer ] 2 [ Integer ] 3 [ Integer ]

condition Integer value, if > 0 triggers recursion with updated arguments

arg1 New value for the first function argument during recursion

arg2 New value for the second function argument during recursion

returns ps.Res (function result) regardless of condition

recur-if\3

Internal recursion control function for three-argument functions. Updates all three arguments and resets if condition > 0.

Args: 4

Types: 1 [ Integer ] 2 [ Integer ] 3 [ Integer ] 4 [ Integer ]

condition Integer value, if > 0 triggers recursion with updated arguments

arg1 New value for the first function argument during recursion

arg2 New value for the second function argument during recursion

arg3 New value for the third function argument during recursion

returns ps.Res (function result) regardless of condition, nil if recursion continues

pass

Accepts a value and a block. It does the block, with value injected, and returns (passes on) the initial value.

Args: 2

Types: 2 [ Block ]

value Any value that will be passed to the block and returned

block Block of code to execute with the value injected

returns The original value, regardless of what the block returns

101 .pass { 202 }
; returns 101

101 .pass { 202 + 303 }
; returns 101

"hello" .pass { .length? }
; returns "hello"

wrap

Executes a wrapper block before and after executing a main block, returning the result of the main block.

Args: 2

Types: 1 [ Block ] 2 [ Block ]

wrapper Block of code to execute before and after the main block

block Main block of code to execute between wrapper executions

returns The result of the main block execution

wrap { prn "*" } { prn "x" }
; prints "*x*"

keep

Do the first block, then the second one but return the result of the first one.

Args: 3

Types: 2 [ Block ] 3 [ Block ]

value Value to be injected into both blocks

block1 First block whose result will be returned

block2 Second block to execute after the first one

returns The result of the first block, ignoring the result of the second block

20 .keep { + 202 } { + 101 }
; returns 222

prns

Prints a value followed by a space, returning the input value.

Args: 1

value Value to print

returns the input value

prns "A"
; prints "A "

prn

Prints a value without adding a newline, returning the input value.

Args: 1

value Value to print

returns the input value

prn "A"
; prints "A"

print

Prints a value followed by a newline, returning the input value.

Args: 1

value Value to print

returns the input value

print "A"
; prints "A
; "

print2

Prints two values separated by a space and followed by a newline, returning the second value.

Args: 2

a First value to print

b Second value to print

returns the second input value

print2 "A" "B"
; prints "A B
; "

prn2

Prints two values separated by a space without a newline, returning the second value.

Args: 2

a First value to print

b Second value to print

returns the second input value

prn2 "A" "B"
; prints "A B"

prns2

Prints two values each followed by a space, returning the second value.

Args: 2

a First value to print

b Second value to print

returns the second input value

prns2 "A" "B"
; prints "A B "

format

Formats a block of values using a format string with {} placeholders, returning the resulting string.

Args: 2

Types: 1 [ String ] 2 [ Block ]

template String with {} placeholders

values Block of values to substitute into the template in order

returns string with placeholders replaced

prnf

Formats and prints a value by replacing {} in the template string, without a newline.

Args: 2

Types: 2 [ String ]

value Value to embed

template String with {} placeholder

returns the input value after printing

printf

Formats and prints a value by replacing {} in the template string, followed by a newline.

Args: 2

Types: 2 [ String ]

value Value to embed

template String with {} placeholder

returns the input value after printing

embed

Embeds a value into a string or URI by replacing {} placeholder with the string representation of the value.

Args: 2

Types: 1 [ String Uri ]

value Value to embed

target String or URI with {} placeholder

returns string or URI with placeholder replaced by the value

embed 42 "v={}"
; returns "v=42"

42 embed 123
; correctly causes error:
; missing argument 2 

prnv

Embeds a value into a string by replacing {} placeholder and prints it without a newline, returning the input value.

Args: 2

Types: 1 [ String ]

value Value to embed

template String with {} placeholder

returns the input value after printing

prnv 42 "v={}"
; prints "v=42"

printv

Embeds a value into a string by replacing {} placeholder and prints it followed by a newline, returning the input value.

Args: 2

Types: 1 [ String ]

value Value to embed

template String with {} placeholder

returns the input value after printing

printv 42 "v={}"
; prints "v=42
; "

probe\

Prints a prefix string followed by detailed type and value information about a value, followed by a newline, returning the input value.

Args: 2

Types: 2 [ String ]

value Value to inspect.

prefix String printed before the value.

returns the input value.

inspect

Returns a string containing detailed type and value information about a value.

Args: 1

value Value to inspect

returns string with diagnostic representation

esc

Creates an ANSI escape sequence by prepending the escape character (\033) to the input string.

Args: 1

Types: 1 [ String ]

str Base string to prefix with escape character

returns string starting with escape character

esc "A" |length?
; returns 2

esc-val

Creates an ANSI escape sequence with an embedded value by replacing {} placeholder and prepending the escape character (\033).

Args: 2

Types: 2 [ String ]

value Value to embed

template String with {} placeholder

returns string starting with escape character and embedded value

esc-val 42 "X={}" |contains "X=42"
; returns true

fail

Creates an error and sets the failure flag, but continues execution (unlike ^fail).

Args: 1

error_info String message, Integer code, or block for multiple parameters

returns error object and sets the failure flag

try { fail "error message" } |type?
; returns error

try { fail "error message" } |message?
; returns "error message"

try { fail 404 } |status?
; returns 404

^fail

Creates an error and immediately returns from the current function with failure state.

Args: 1

error_info String message, Integer code, or block for multiple parameters

returns error object and sets both failure and return flags

ff:: fn { } { ^fail "error message" } ff |disarm |type?
; returns error

ff:: fn { } { ^fail "error message" } ff |disarm |message?
; returns "error message"

ff:: fn { } { ^fail 404 } ff |disarm |status?
; returns 404

ff:: fn { } { ^fail 'user-error } ff |disarm |kind?
; returns user-error

refail

Re-raises an existing error with additional context.

Args: 2

Types: 1 [ Error ]

error Error to re-raise.

error-info Additional String, Integer, or Block context.

returns a new Error with the additional context.

failure

Creates an error object without setting any flags (unlike fail and ^fail).

Args: 1

error_info String message, Integer code, or block for multiple parameters

returns error object without setting any flags

failure "error message" |type?
; returns error

failure "error message" |message?
; returns "error message"

failure 404 |status?
; returns 404

empty

Creates an 404 error object without setting any flags.

error_info String message, Integer code, or block for multiple parameters

returns error object without setting any flags

failure "error message" |type?
; returns error

failure "error message" |message?
; returns "error message"

failure 404 |status?
; returns 404

failure\wrap

Creates a new error that wraps an existing error, allowing for error chaining.

Args: 2

Types: 2 [ Error ]

error_info String message, Integer code, or block for multiple parameters

error Error object to wrap

returns new error object that wraps the provided error

failure\wrap "outer error" failure "inner error" |message?
; returns "outer error"

failure\wrap "outer error" failure "inner error" |type?
; returns error

is-error

Returns true if the value is an error, false otherwise.

Args: 1

value Any value to check

returns boolean true if the value is an error, false otherwise

is-error failure "test"
; returns true

is-error 123
; returns false

error-kind?

Returns the kind of an error, or void if not an error.

Args: 1

value Any value to check

returns the kind of the error as a word, or void if not an error

error-kind? failure { 'syntax-error 404 "Syntax error" }
; returns syntax-error

error-kind? 123
; returns _

is-error-of-kind

Returns true if the value is an error of the specified kind, false otherwise.

Args: 2

Types: 2 [ Word Tagword ]

error Error object to check

kind Word or tagword representing the error kind to check against

returns boolean true if the error is of the specified kind, false otherwise

is-error-of-kind failure { 'syntax-error 404 "Syntax error" } 'syntax-error
; returns true

is-error-of-kind failure { 'syntax-error 404 "Syntax error" } 'runtime-error
; returns false

cause?

Extracts the root cause from an error chain by traversing the Parent references.

Args: 1

Types: 1 [ Error ]

error Error object to extract the root cause from

returns the root cause error from an error chain

cause? failure\wrap "outer error" failure "inner error" |message?
; returns "inner error"

cause? failure "single error" |message?
; returns "single error"

status?

Extracts the numeric status code from an error object.

Args: 1

Types: 1 [ Error ]

error Error object to extract status code from

returns integer status code of the error

failure 404 |status?
; returns 404

failure "message" |status?
; returns 0

"not an error" |status?
; correctly causes error:
; `status?` expected Error for argument 1 

message?

Extracts the message string from an error object.

Args: 1

Types: 1 [ Error ]

error Error object to extract message from

returns string message of the error

failure "error message" |message?
; returns "error message"

failure 404 |message?
; returns ""

"not an error" |message?
; correctly causes error:
; `message?` expected Error for argument 1 

details?

Extracts additional details from an error object as a dictionary.

Args: 1

Types: 1 [ Error ]

error Error object to extract additional details from

returns dictionary containing any additional values stored in the error

"not an error" |details?
; correctly causes error:
; `details?` expected Error for argument 1 

has-failed

Tests if a value is an error object, returning true for errors and false for non-errors.

Args: 1

value Any value to check

returns boolean true if the value is an error, false otherwise

has-failed failure "error"
; returns true

has-failed "not an error"
; returns false

has-failed 123
; returns false

has-failed try { fail "error" }
; returns true

is-failure

Checks if a value is a failure/error type. Unlike has-failed, this doesn't accept failures - the value must already be disarmed.

Args: 1

value Any value to check (must already be disarmed if it was a failure)

returns boolean true if the value is an error type, false otherwise

try { fail "error" } |disarm |is-failure
; returns true

failure "error" |is-failure
; returns true

123 |is-failure
; returns false

"hello" |is-failure
; returns false

is-success

Returns true for any value that is not a failure/error type. The opposite of is-failure.

Args: 1

value Any value to check (must already be disarmed if it was a failure)

returns boolean true if the value is not an error type, false if it is an error

123 |is-success
; returns true

"hello" |is-success
; returns true

{ 1 2 3 } |is-success
; returns true

failure "error" |is-success
; returns false

try { fail "error" } |disarm |is-success
; returns false

disarm

Clears the failure flag while preserving the error object, allowing error inspection without propagation.

Args: 1

error Error object to disarm

returns the original error object, but clears the failure flag

try { fail "error" |disarm } |type?
; returns error

try { fail "error" |disarm |message? }
; returns "error"

try { fail "error" } |has-failed
; returns true

try { fail "error" |disarm } |has-failed
; returns true

check

Checks if a value is in failure state and wraps it with a new error if so, otherwise returns the original value.

Args: 2

value Value to check for failure state

error_info Error information to use if value is in failure state

returns original value if not in failure state, or a new error wrapping the original error

5 |check "Value must be positive"
; returns 5

try { fail "Original error" |check "Wrapped error" } |message?
; returns "Wrapped error"

try { fail "Original error" |check "Wrapped error" } |details? |type?
; returns dict

^check

Like 'check' but also sets the return flag to immediately exit the current function.

Args: 2

value Value to check for failure state

error_info Error information to use if value is in failure state

returns original value if not in failure state, or immediately returns from function with a new error

fn { x } { x |^check "Error in function" } |apply [ 5 ]
; returns 5

ff:: fn { x } { fail "Original" |^check "Wrapped" } ff 5 |disarm |message?
; returns "Wrapped"

^ensure

Checks if a value is truthy and returns it if so, otherwise creates an error and immediately returns from the function.

Args: 2

condition Value to test for truthiness

error_info Error information to use if condition is not truthy

returns condition value if truthy, or immediately returns from function with an error

fn { x } { x |^ensure "Must be positive" } |apply [ 5 ]
; returns 5

ff:: fn { x } { x > 0 |^ensure "Must be positive" } ff -1 |disarm |message?
; returns "Must be positive"

ensure

Checks if a value is truthy and returns it if so, otherwise creates an error with the failure flag set.

Args: 2

condition Value to test for truthiness

error_info Error information to use if condition is not truthy

returns condition value if truthy, or creates an error with failure flag set

5 > 0 |ensure "Must be positive"
; returns true

try { -1 > 0 |ensure "Must be positive" } |message?
; returns "Must be positive"

requires-one-of

Validates that a value matches one of the provided options, failing with a descriptive error if not.

Args: 2

Types: 2 [ Block ]

value Value to check against valid options

options Block containing valid values

returns original value if it matches one of the options, or creates an error with failure flag set

"a" |requires-one-of { "a" "b" "c" }
; returns "a"

"b" |requires-one-of { "a" "b" "c" }
; returns "b"

try { "x" |requires-one-of { "a" "b" "c" } } |message? |contains "must be one of"
; returns true

try { "x" |requires-one-of { "a" "b" "c" } } |message? |contains "[String: x]"
; returns true

try { 5 |requires-one-of { 1 2 3 } } |message? |contains "5"
; returns true

^requires-one-of

Validates that a value matches one of the provided options, failing with a descriptive error if not.

Args: 2

Types: 2 [ Block ]

value Value to check against valid options

options Block containing valid values

returns original value if it matches one of the options, or creates an error with failure flag set

"a" |requires-one-of { "a" "b" "c" }
; returns "a"

"b" |requires-one-of { "a" "b" "c" }
; returns "b"

try { "x" |requires-one-of { "a" "b" "c" } } |message? |contains "must be one of"
; returns true

try { "x" |requires-one-of { "a" "b" "c" } } |message? |contains "[String: x]"
; returns true

try { 5 |requires-one-of { 1 2 3 } } |message? |contains "5"
; returns true

ensure\with

Injects a value into a validation block and returns the value if the block is truthy, otherwise creates an error.

Args: 3

Types: 2 [ Block ]

value Value to inject into the validation block

block Block that receives the value and returns truthy/falsy result

error_info Error information to use if block returns falsy

returns original value if block returns truthy, or creates an error with failure flag set

dict { "status" 200 } |ensure\with { -> "status" = 200 } "status check failed"
; returns dict { status 200 }

try { dict { "status" 404 } |ensure\with { -> "status" = 200 } "status check failed" } |message?
; returns "status check failed"

^ensure\with

Like ensure\with but also sets the return flag to immediately exit the current function.

Args: 3

Types: 2 [ Block ]

value Value to inject into the validation block

block Block that receives the value and returns truthy/falsy result

error_info Error information to use if block returns falsy

returns original value if block returns truthy, or immediately returns from function with an error

ff:: fn { val } { val |^ensure\with { -> "status" = 200 } "status check failed" } ff dict { "status" 404 } |disarm |message?
; returns "status check failed"

fix

Handles errors by executing a block if the value is in failure state, clearing the failure flag.

Args: 2

Types: 2 [ Block ]

value Value to check for failure state

handler Block to execute if value is in failure state

returns original value if not in failure state, or result of executing the handler block

5 |fix { + 10 }
; returns 5

try { fail "error" |fix { "fixed" } }
; returns "fixed"

try { fail "error" |fix { fail "new error" } } |message?
; returns "new error"

^fix

Like 'fix' but also sets the return flag to immediately exit the current function with the handler result.

Args: 2

Types: 2 [ Block ]

value Value to check for failure state

handler Block to execute if value is in failure state

returns original value if not in failure state, or immediately returns from function with handler result

fn { x } { x |^fix { "fixed" } } |apply [ 5 ]
; returns 5

ff:: fn { x } { fail "error" |^fix { "fixed" } } ff 5
; returns "fixed"

fix\either

Executes one of two blocks depending on whether the value is in failure state.

Args: 3

Types: 2 [ Block ] 3 [ Block ]

value Value to check for failure state

error_handler Block to execute if value is in failure state

success_handler Block to execute if value is not in failure state

returns result of executing the appropriate handler block

fix\either failure "error" { "fixed" } { "not fixed" }
; returns "fixed"

fix\either 5 { "fixed" } { "not fixed" }
; returns "not fixed"

fix\else

Executes a block if the value is not in failure state, otherwise returns the original value.

Args: 2

Types: 2 [ Block ]

value Value to check for failure state

success_handler Block to execute if value is not in failure state

returns result of executing the success handler if value is not in failure state, or the original value

5 |fix\else { "not fixed" }
; returns "not fixed"

try { fail "error" |fix\else { "not fixed" } } |message?
; returns "error"

fix\continue

Executes one of two blocks depending on whether the value is in failure state, like an error-handling if/else.

Args: 3

Types: 2 [ Block ] 3 [ Block ]

value Value to check for failure state

error_handler Block to execute if value is in failure state

success_handler Block to execute if value is not in failure state

returns result of executing the appropriate handler block

5 |fix\continue { "error handler" } { "success handler" }
; returns "success handler"

try { fail "error" |fix\continue { "error handler" } { "success handler" } }
; returns "error handler"

continue

Executes a block only if the value is not in failure state, opposite of 'fix'.

Args: 2

Types: 2 [ Block ]

value Value to check for failure state

block Block to execute if value is not in failure state

returns result of executing the block if value is not in failure state, or the original value

5 |continue { + 10 }
; returns 15

try { fail "error" |continue { + 10 } }
; returns failure { 0 "error" }

^fix\match

Error handling switch that matches error codes with handler blocks and sets the return flag.

Args: 2

Types: 2 [ Block ]

error Error object to match against

cases Block containing error codes and corresponding handler blocks

returns result of executing the matching handler block, or the original error if no match

^fix\match failure 404 { 404 { "Not Found" } 500 { "Server Error" } }
; returns "Not Found"

^fix\match failure 500 { 404 { "Not Found" } 500 { "Server Error" } }
; returns "Server Error"

^fix\match failure 403 { 404 { "Not Found" } 500 { "Server Error" } _ { "Unknown Error" } }
; returns "Unknown Error"

try

Takes a block of code and does (runs) it.

Args: 1

Types: 1 [ Block ]

block Block to evaluate, capturing errors.

returns the block result, or an Error value if evaluation fails.

try { 123 + 123 }
; returns 246

try { 123 + "asd" } |type?
; returns error

try { 123 + } |type?
; returns error

try { fail "oops" } |message?
; returns "oops"

try-all

Executes a block and returns a result tuple [success, result], where success is true if no error occurred.

Args: 1

Types: 1 [ Block ]

block Block of code to execute

returns a block containing [success, result], where success is true if no error occurred

try-all { 1 + 2 }
; returns { true 3 }

try-all { fail "custom error" } |first
; returns false

try\in

Takes a Context and a Block. It Does a block inside a given Context.

Args: 2

Types: 1 [ Context ] 2 [ Block ]

context Context in which to evaluate the block.

block Block to evaluate, capturing errors.

returns the block result, or an Error value if evaluation fails.

c: context { x: 100 } try\in c { x * 9.99 }
; returns 999

c: context { x:: 100 } try\in c { inc! 'x }
; returns 101

c: context { x:: 100 } try\in c { x:: 200 , x }
; returns 200

c: context { x:: 100 } try\in c { x:: 200 } c/x
; returns 200

c: context { x: 100 } try\in c { inc! 'y } |type?
; returns error

finally

Executes a block and ensures another block is executed afterward, regardless of errors.

Args: 2

Types: 1 [ Block ] 2 [ Block ]

main-block Block of code to execute

finally-block Block to execute afterward, regardless of errors

returns result of the main block, preserving any failure state

finally { 1 + 2 } { print "cleanup" }
; returns 3

try { finally { fail "error" } { print "cleanup" } } |message?
; returns "error"

retry

Executes a block and retries it up to N times if it results in a failure.

Args: 2

Types: 1 [ Integer ] 2 [ Block ]

retries Integer number of retries to attempt

block Block of code to execute and potentially retry

returns result of the block if successful, or the last failure if all retries fail

retry 3 { 10 + 1 }
; returns 11

persist

Executes a block repeatedly until it succeeds (no failure), then returns the successful result. Gives up after 1000 attempts.

Args: 1

Types: 1 [ Block ]

block Block of code to execute repeatedly until it succeeds

returns result of the block when it finally succeeds (no failure), or error if 1000 attempts exceeded

persist { 10 + 1 }
; returns 11

persist { fail "always fails" }
; correctly causes error:
; Persist failed: Block did not succeed after 1000 attempts 

timeout

Executes a block of code with a timeout, failing if execution exceeds the specified duration in milliseconds.

Args: 2

Types: 1 [ Integer ] 2 [ Block ]

ms Integer timeout duration in milliseconds

block Block of code to execute with a timeout

returns result of the block if it completes within the timeout, or a timeout error

timeout 5000 { "ok" }
; returns "ok"

try { timeout 100 { sleep 1000 , "ok" } } |message? |contains "timed out"
; returns true

mth

Fast infix math evaluator with proper operator precedence (+,-,*,/,//,%,<,>,=,<=,>=,!=). Single-pass Shunting-yard, direct Go arithmetic, no builtin lookup.

Args: 1

Types: 1 [ Block ]

block Block containing an infix math expression

returns result of evaluating the expression with proper operator precedence

mth { 1 + 2 }
; returns 3

mth { 2 + 3 * 4 }
; returns 14

mth { 10 - 5 - 2 }
; returns 3

mth { 8 // 3 }
; returns 2

mth { 8 % 3 }
; returns 2

mth { 5 + 5 < 10 }
; returns false

mth { 5 + 5 <= 10 }
; returns true

mth { 5 + 4 < 10 }
; returns true

mth { 1 + 2 * 3 }
; returns 7

a: 5 mth { a * 2 }
; returns 10

a: 3 b: 4 mth { a * a + b * b }
; returns 25

input-intent

Declares a semantic input point: input-intent name validator-block provider-block. In scenario mode, returns the mocked value for the given intent name; otherwise evaluates the provider block. The resulting value is always validated using the validation dialect block.

Args: 3

Types: 1 [ Tagword Word String ] 2 [ Block ] 3 [ Block ]

name Word, String, or Tagword identifying the intent.

validator Validation-dialect block used to validate the result.

provider Block that produces the real value outside scenario mode.

returns The validated value, or the configured mock value in scenario mode.

input-intent 'username { string? } { "real-user" }

output-intent

Logs an output with optional inline fields and executes the side-effect block unless in scenario mode. Usage: output-intent payload-or-name { fields } { side-effect }.

Args: 3

Types: 2 [ Block ] 3 [ Block ]

payload Name or value to log and return.

fields Block of additional values to include in the log entry.

side-effect Block to execute outside scenario mode.

returns The first argument (payload or name), so it can be captured or piped.

output-intent "user-login" { "alice" } { print "logged in" }

table

Creates a table by accepting block of column names and flat block of values

Args: 2

Types: 1 [ Block ] 2 [ Block ]

columns

data

returns new Table built from the column names and row values.

table { "a" } { 1 2 } |type?
; returns table

table { 'a } { 1 2 } |type?
; returns table

table { 'a 'b } { 1 2 3 4 } |length?
; returns 2

table\columns

Creats a table by accepting a block of columns

Args: 2

columns - names of the columns

data - block or list of columns (each column is a block or list)

returns new Table built from the provided columns.

table\columns { "a" } { { 1 2 3 } } |type?
; returns table

table\columns { "a" "b" } { { 1 2 3 } { 4 5 6 } } |length?
; returns 3

table\columns { 'a 'b } { { 1 2 } { "x" "y" } }

table\rows

Creates a table by accepting a block or list of rows

Args: 2

Types: 2 [ Block List ]

columns - names of the columns

data - block or list of rows (each row is a block or list)

returns new Table built from the provided rows.

table\rows { 'a 'b } { { 1 2 } { 3 4 } }
; returns table { "a" "b" } [ 1 2 3 4 ]

table\rows { 'a 'b } list [ list [ 1 2 ] list [ 3 4 ] ] |type?
; returns table

to-table

Creates a table by accepting block or list of dicts

Args: 1

Types: 1 [ Block List ]

data

returns Table built from the block or list of dicts.

to-table list [ dict { "a" 1 } dict { "a" 2 } ] |type?
; returns table

to-table list [ dict { "a" 1 "b" "Jim" } dict { "a" 2 "b" "Bob" } ] |header? |sort
; returns list { "a" "b" }

to-table list [ dict { "a" 1 "b" "Jim" } dict { "a" 2 "b" "Bob" } ] |column? "b" |first
; returns "Jim"

to-dict

Creates a dict from a two-column table, using the first column as keys and the second column as values.

Args: 1

Types: 1 [ Table ]

table - a two-column table where the first column becomes keys and the second becomes values

returns a dict mapping each value in the first column (as string key) to the corresponding value in the second column

table { 'k 'v } { "a" 1 "b" 2 } |to-dict |-> "a"
; returns 1

table { 'k 'v } { "x" 100 "y" 200 } |to-dict |type?
; returns dict

table { 'k 'v } { "a" 1 "b" 2 } |to-dict |length?
; returns 2

table { 'name 'score } { "Alice" 95 "Bob" 87 } |to-dict |-> "Bob"
; returns 87

table { 'a } { 1 2 3 } |to-dict
; correctly causes error:
; `to-dict`: to-dict requires a table with exactly 2 columns, got 1 

where-equal

Returns table of rows where specific colum is equal to given value.

Args: 3

Types: 1 [ Table ] 2 [ Word String ]

sheet

column

value

returns new Table containing rows whose column equals the value.

table { 'a } { 1 2 3 2 } |where-equal "a" 2 |length?
; returns 2

filtering for rows with the name "Enno"
sheet: table { "name" } { "Enno" "Enya" "Enid" "Bob" "Bill" }
sheet .where-equal 'name "Enno"

where-not-equal

Returns table of rows where specific colum is not equal to given value.

Args: 3

Types: 1 [ Table ] 2 [ Word String ]

sheet

column

value

returns new Table containing rows whose column does not equal the value.

table { 'a } { 1 2 3 2 } |where-not-equal "a" 2 |length?
; returns 2

where-void

Returns table of rows where specific colum is void.

Args: 2

Types: 1 [ Table ] 2 [ Word String ]

sheet

column

returns new Table containing rows where the column is void.

table { 'a } { 1 _ 3 _ } |where-void "a" |length?
; returns 2

where-match

Returns table of rows where a specific colum matches a regex.

Args: 3

Types: 1 [ Table ] 2 [ Native Word String ] 3 [ Native ]

sheet

column

regex

returns new Table containing rows whose column matches the regular expression.

table { 'a } { "1" "2" "a3" "2b" } |where-match 'a regex "^[0-9]$" |length?
; returns 2

filting for names that start with "En"
sheet: table { "name" } { "Enno" "Enya" "Enid" "Bob" "Bill" }
sheet .where-match 'name "En.+"

where-contains

Returns table of rows where specific colum contains a given string value.

Args: 3

Types: 1 [ Table ] 2 [ Word String ] 3 [ String ]

sheet

column

substring

returns new Table containing rows whose column contains the substring.

table { 'a } { "1" "2" "a3" "2b" } |where-contains 'a "2" |length?
; returns 2

sheet: table { "name" } { "Enno" "Enya" "Enid" "Bob" "Bill" "Benn" }
sheet .where-contains 'name "nn"

where-not-contains

Returns table of rows where specific colum does not contain a given string value.

Args: 3

Types: 1 [ Table ] 2 [ Word String ] 3 [ String ]

sheet

column

substring

returns new Table containing rows whose column does not contain the substring.

table { 'a } { "1" "2" "a3" "2b" } |where-not-contains 'a "3" |length?
; returns 3

sheet: table { "name" } { "Enno" "Enya" "Enid" "Bob" "Bill" "Benn" }
sheet .where-not-contains 'name "nn"

where-greater

Returns table of rows where specific colum is greater than given value.

Args: 3

Types: 1 [ Table ] 2 [ Word String ]

sheet

column

value

returns new Table containing rows whose column is greater than the value.

table { 'a } { 1 2 3 2 } |where-greater 'a 1 |length?
; returns 3

sheet: table { "name" "age" } { "Enno" 30 "Enya" 25 "Enid" 40 "Bob" 19 "Bill" 45 "Benn" 29 }
sheet .where-greater 'age 29

where-lesser

Returns table of rows where specific colum is lesser than given value.

Args: 3

Types: 1 [ Table ] 2 [ Word String ]

sheet

column

value

returns new Table containing rows whose column is less than the value.

table { 'a } { 1 2 3 2 } |where-lesser 'a 3 |length?
; returns 3

filting for names that contain "nn"
sheet: table { "name" "age" } { "Enno" 30 "Enya" 25 "Enid" 40 "Bob" 19 "Bill" 45 "Benn" 29 }
sheet .where-lesser 'age 29

where-between

Returns table of rows where specific colum is between given values.

Args: 4

Types: 1 [ Table ] 2 [ Word String ]

sheet

column

lower-limit

upper-limit

returns new Table containing rows whose column is between the limits (exclusive).

table { 'a } { 1 2 3 2 } |where-between 'a 1 3 |length?
; returns 2

filtering for folks in their 20s
sheet: table { "name" "age" } { "Enno" 30 "Enya" 25 "Enid" 40 "Bob" 19 "Bill" 45 "Benn" 29 }
sheet .where-between 'age 19 30

where-between\inclusive

Returns table of rows where specific colum is between given values (inclusive).

Args: 4

Types: 1 [ Table ] 2 [ Word String ]

sheet

column

lower-limit

upper-limit

returns new Table containing rows whose column is within the inclusive limits.

table { 'a } { 1 2 3 2 5 } |where-between\inclusive 'a 2 3 |length?
; returns 3

where-in

Returns table of rows where specific colum value is found in block of values.

Args: 3

Types: 1 [ Table ] 2 [ Word String ] 3 [ Block ]

sheet

column

values-filtered-for

returns new Table containing rows whose column value is in the provided block.

table { "name" "age" } { "Enno" 30 "Enya" 25 "Bob" 19 } |where-in 'name { "Enno" "Enya" "Roger" } |column? "age"
; returns { 30 25 }

filtering for folks named "Enno" or "Enya"
sheet: table { "name" "age" } { "Enno" 30 "Enya" 25 "Enid" 40 "Bob" 19 "Bill" 45 "Benn" 29 }
sheet .where-in 'name { "Enno" "Enya" }

where-not-in

Returns table of rows where specific colum value is not found in block of values.

Args: 3

Types: 1 [ Table ] 2 [ Word String ] 3 [ Block ]

sheet

column

values-filtered-for

returns new Table containing rows whose column value is not in the provided block.

table { "name" "age" } { "Enno" 30 "Enya" 25 "Bob" 19 } |where-not-in 'name { "Enno" "Enya" "Roger" } |column? "age"
; returns { 19 }

filtering for folks named "Enno" or "Enya"
sheet: table { "name" "age" } { "Enno" 30 "Enya" 25 "Enid" 40 "Bob" 19 "Bill" 45 "Benn" 29 }
sheet .where-not-in 'name { "Enno" "Enya" }

where

Returns table of rows where code block evaluates to true for the column value.

Args: 3

Types: 1 [ Table ] 2 [ Word String Block ] 3 [ Block Builtin Function ]

table

column - column name (word or string) or block of column names

code - block that receives column value (or has columns as words) and returns truthy/falsy

returns new Table containing rows for which the block returns a truthy value.

table { 'a } { 1 2 3 4 } |where 'a { > 2 } |length?
; returns 2

table { 'a } { 1 2 3 4 } |where 'a { .is-even } |length?
; returns 2

table { 'name 'age } { "Jim" 30 "Jane" 25 } |where 'age { > 26 } |column? 'name
; returns { "Jim" }

table { 'a 'b } { 1 10 2 20 3 30 } |where { 'a 'b } { ( a + b ) > 25 } |length?
; returns 1

table { 'a 'b } { 1 10 2 20 3 30 } |where { 'a 'b } { all { a > 1 b > 15 } } |length?
; returns 2

table { 'a 'b } { 1 10 2 20 3 30 } |where { "a" "b" } { all { a > 1 b > 15 } } |length?
; returns 2

table { 'a 'b } { 1 10 2 20 3 30 } |where { 'a 'b } { > 1 } |length?
; returns 2

table { "name" "age" } { "Jim" 30 "Jane" 25 "Bob" 35 } |where 'age { > 26 }
table { "a" "b" } { 1 10 2 20 3 30 } |where { 'a 'b } { ( a + b ) > 25 }

distinct

Returns table with duplicate rows removed based on specified column(s).

Args: 2

Types: 1 [ Table ] 2 [ Word String Block ]

table

column - column name (word or string) or block of column names

returns new Table with duplicate rows removed.

table { 'a } { 1 2 1 3 2 } |distinct 'a |length?
; returns 3

table { 'a 'b } { 1 10 1 10 1 20 } |distinct { 'a 'b } |length?
; returns 2

table { "name" "age" } { "Jim" 30 "Jane" 25 "Jim" 30 } |distinct 'name
table { "a" "b" } { 1 10 1 20 2 10 } |distinct { 'a 'b }

fill-void

Returns table with void values in specified column replaced with given value.

Args: 3

Types: 1 [ Table ] 2 [ Word String ]

table

column - column name (word or string)

value - value to replace void with

returns new Table with void cells replaced in the specified column.

table { 'a } { 1 _ 3 _ } |fill-void 'a 0 |column? 'a
; returns { 1 0 3 0 }

table { 'a } { 1 _ 3 _ } |fill-void 'a 99 |column? 'a |sum
; returns 202

table { "name" "age" } { "Jim" 30 "Jane" _ } |fill-void 'age 0

count-where

Returns count of rows where code block evaluates to true for the column value.

Args: 3

Types: 1 [ Table ] 2 [ Word String Block ] 3 [ Block Builtin Function ]

table

column - column name (word or string) or block of column names

code - block that receives column value and returns truthy/falsy

returns Integer count of matching rows.

table { 'a } { 1 2 3 4 } |count-where 'a { > 2 }
; returns 2

table { 'a } { 1 2 3 4 } |count-where 'a { .is-even }
; returns 2

table { 'a 'b } { 1 10 2 20 3 30 } |count-where { 'a 'b } { ( a + b ) > 25 }
; returns 1

table { "name" "age" } { "Jim" 30 "Jane" 25 "Bob" 35 } |count-where 'age { > 26 }

add-row

Returns a table with new-row added to it

Args: 2

Types: 1 [ Table ] 2 [ Block List ]

sheet

new-row

returns new Table with the row appended.

table { "a" "b" } { 6 60 7 70 } |add-row { 8 80 } |-> 2 |-> "b"
; returns 80

get-rows

Get rows as a native. This value can be used in `add-rows` and `add-rows!`

Args: 1

Types: 1 [ Table ]

sheet

returns native rows value that can be passed to add-rows or add-rows!.

table { "a" "b" } { 6 60 7 70 } |get-rows |type?
; returns native

add-rows

Add one or more rows to a table

Args: 2

Types: 1 [ Table ] 2 [ Block Native ]

sheet - the sheet that is getting rows added to it

rows - a block containing one or more rows worth of values, or a TableRow Native value

returns new Table with the rows appended.

ref table { "a" "b" } { 6 60 7 70 } :sheet sheet .deref |add-rows [ 3 30 ] |length?
; returns 3

ref table { "a" "b" } { 1 80 2 90 } :sheet sheet .deref |add-rows { 3 30 } |length?
; returns 3

add-rows!

Add one or more rows to a table ref

Args: 2

Types: 1 [ Table PersistentTable ] 2 [ Block Native ]

sheet - the reference to the sheet that is getting rows added to it

rows - a block containing one or more rows worth of values, or a TableRow Native value

returns the updated table.

ref table { "a" "b" } { 1 10 2 20 } :sheet sheet .add-rows! [ 3 30 ] sheet .deref .length?
; returns 3

update-row!

Update the row at the given index.

Args: 3

Types: 2 [ Integer ] 3 [ Function Dict TableRow ]

sheet-ref - A ref to a table

idx - the index of the row to update, 1-based

updater - One of either a function, a dict, or a Table Row

returns the updated table reference.

spr1: ref table { "a" "b" } { 1 10 2 20 } spr1 .update-row! 1 dict [ "a" 111 ] spr1 .deref .A1
; returns 111

spr1: ref table { "a" "b" } { 1 10 2 20 } incrA: fn { row } { row ++ [ "a" ( "a" <- row ) + 9 ] } update-row! spr1 1 ?incrA spr1 |deref |A1
; returns 10

remove-row!

Remove a row from a table by index

Args: 2

Types: 1 [ Table ] 2 [ Block Native ]

sheet-ref

row-idx - Index of row to remove, 1-based

returns the updated table reference.

spr1: ref table { "a" "b" } { 1 10 2 20 } spr1 .remove-row! 1 spr1 .deref .A1
; returns 2

columns?

Returns table with just given columns. Use lsetwords (:newName) to rename the previous column.

Args: 2

Types: 1 [ Block Table ]

sheet Table to select columns from.

columns Block of column names; lsetwords rename the preceding column.

returns new Table containing only the selected columns.

table { "name" "age" "job_title" } { "Bob" 25 "Janitor" "Alice" 29 } |columns? { 'name 'age } |header?
; returns list { "name" "age" }

Select "name" and "age" columns
sheet: table { "name" "age" "job_title" } { "Bob" 25 "Janitor" "Alice" 29 "Librarian" "Charlie" 19 "Line Cook" }
sheet .columns? { 'name 'age }

header?

Gets the column names (header) as block.

Args: 1

Types: 1 [ Table ]

sheet Table to read the header from.

returns Block of column names.

table { "age" "name" } { 123 "Jim" 29 "Anne" } |header?
; returns list { "age" "name" }

Get sheet column names
sheet: table { "name" "age" "job_title" } { "Bob" 25 "Janitor" "Alice" 29 "Librarian" "Charlie" 19 "Line Cook" }
sheet .header? ; { "name" "age" "job_title" }

column?

Gets all values of a column as a block.

Args: 2

Types: 1 [ Table ] 2 [ Word String ]

sheet Table or Block to read from.

column Word or String column name, or Integer index for a Block.

returns Block of values from the requested column.

table { "name" "age" "job_title" } { "Bob" 25 "Janitor" "Alice" 29 "Teacher" } |column? 'name
; returns { "Bob" "Alice" }

Get sheet column names
sheet: table { "name" "age" "job_title" } { "Bob" 25 "Janitor" "Alice" 29 "Librarian" "Charlie" 19 "Line Cook" }
sheet .column? 'name ; => { "Bob" "Alice" "Charlie" }

drop-column

Remove a column from a table. Returns new table

Args: 2

Types: 1 [ Table ] 2 [ Word String Block ]

sheet Table to modify.

column Word, String, or Block of column names to drop.

returns new Table without the dropped column(s).

table { "name" "age" "job_title" } { "Bob" 25 "Janitor" "Alice" 29 "Librarian" } |drop-column "name" |header?
; returns list { "age" "job_title" }

Drop "job_title" column from sheet
sheet: table { "name" "age" "job_title" } { "Bob" 25 "Janitor" "Alice" 29 "Librarian" "Charlie" 19 "Line Cook" }
sheet .drop-column 'job_title ;

rename-column!

Remove a column from a table. Returns new table

Args: 3

Types: 1 [ Table ] 2 [ Word Block ]

sheet-ref reference to the Table.

old-name String current column name.

new-name String new column name.

returns the updated table reference.

tab: ref table { "name" "age" } { "Bob" 25 "Alice" 29 "Charlie" 19 } tab .rename-column! "name" "first_name" , tab .header?
; returns list { "first_name" "age" }

gen-column

Adds a new column to table. Changes in-place and returns the new table.

Args: 4

Types: 1 [ Table ] 2 [ Word ] 3 [ Block ] 4 [ Block ]

sheet Table to modify.

new-column Word or String name for the new column.

source Word/String source column, or Block of values.

generator Block or function producing values for the new column.

returns the updated table.

table { "name" "age" } { "Bob" 25 "Alice" 29 "Charlie" 19 } |gen-column 'job { } { "Cook" } |column? "job"
; returns { "Cook" "Cook" "Cook" }

table { "email" } { "john@example.com" "jane@test.org" } |gen-column 'domain 'email [ regex ".*@(.+)$" "$1" ] |column? "domain"
; returns { "example.com" "test.org" }

Add a column to a sheet
sheet: table { "name" "age" } { "Bob" 25 "Alice" 29 "Charlie" 19 }
sheet .gen-column 'job_title { "Jantior" "Librarian" "Line Cook" } ;
Generate column using regex replacement
sheet: table { "email" } { "john@example.com" "jane@test.org" "bob@company.net" }
sheet .gen-column 'domain 'email { regex "@(.+)$" "$1" }

update-column!

Updates all cells in a column by applying a function that receives the cell value and the row.

Args: 3

Types: 2 [ Word String ] 3 [ Function ]

table-ref - a reference to the table to update

column-name - name of the column to update (word or string)

fn - function that accepts (cell, row) and returns the new cell value

returns the updated table reference.

ref table { "a" "b" } { 1 10 2 20 } :tab , tab .update-column! "a" fn { c r } { c + 100 } , tab .deref .column? "a"
; returns { 101 102 }

ref table { "a" "b" } { 1 10 2 20 } :tab , tab .update-column! "a" fn { c r } { r -> "b" } , tab .deref .column? "a"
; returns { 10 20 }

update column "a" by adding 1 to each cell
table { "a" "b" } { 123 234 334 556 } :tab
tab .update-column! "a" fn { cell row } { cell + 1 }
; column "a" now contains { 124 335 }

add-column

Adds a new column to table with the given data. Returns the modified table.

Args: 3

Types: 1 [ Table ] 2 [ Word String ] 3 [ Block List ]

table - the table to add a column to

column-name - name of the new column (word or string)

data - block or list containing values for the new column (must match number of rows)

returns the updated table.

table { "a" "b" } { 1 10 2 20 3 30 } |add-column 'c { 100 200 300 } |column? "c"
; returns { 100 200 300 }

table { "a" } { 1 2 3 } |add-column 'b list [ "x" "y" "z" ] |column? "b"
; returns { "x" "y" "z" }

order-by!

Sorts row by given column, changes table in place.

Args: 3

Types: 1 [ Table ] 2 [ Word ] 3 [ Word ]

sheet Table to sort in place.

column Word or String column name.

direction Word asc or desc.

returns the updated table.

tab: table { "name" "age" } { "Bob" 25 "Alice" 29 "Charlie" 19 } tab .order-by! 'age 'asc |column? "age"
; returns { 19 25 29 }

Order by age ascending
sheet: table { "name" "age" } { "Bob" 25 "Alice" 29 "Charlie" 19  }
sheet .order-by! 'age 'asc

order-by

Sorts row by given column, changes table in place.

Args: 3

Types: 1 [ Table ] 2 [ Word ] 3 [ Word ]

sheet Table to sort.

column Word or String column name.

direction Word asc or desc.

returns new sorted Table.

tab: table { "name" "age" } { "Bob" 25 "Alice" 29 "Charlie" 19 } |order-by 'age 'desc |column? "age"
; returns { 29 25 19 }

Order by age ascending
sheet: table { "name" "age" } { "Bob" 25 "Alice" 29 "Charlie" 19  }
sheet .order-by 'age 'asc

add-indexes!

Creates an index for all values in the provided columns. Changes in-place and returns the new table.

Args: 2

Types: 1 [ Table ] 2 [ Block ]

sheet Table to modify.

columns Block of column names to index.

returns the updated table.

table { "name" "age" } { "Bob" 25 "Alice" 29 "Charlie" 19 } |add-indexes! { name } |indexes?
; returns { "name" }

indexes?

Returns the columns that are indexed in a table.

Args: 1

Types: 1 [ Table ]

sheet Table to inspect.

returns Block of indexed column names.

table { "name" "age" } { "Bob" 25 "Alice" 29 "Charlie" 19 } |add-indexes! { name age } |indexes? |length?
; returns 2

autotype

Takes a table and tries to determine and change the types of columns.

Args: 2

Types: 1 [ Table ] 2 [ Decimal ]

sheet Table whose column types should be inferred.

percent Decimal fraction of values that must convert for a column to change type.

returns the updated table with inferred column types.

table { "age" } { 123 29 19 } |autotype 1 |types?
; returns { integer }

left-join

Left joins two tables on the given columns.

Args: 4

Types: 1 [ Table ] 2 [ Table ] 3 [ Word String ] 4 [ Word String ]

left left Table.

right right Table.

left-column Word or String join column in the left table.

right-column Word or String join column in the right table.

returns new joined Table including all left-table rows.

names: table { "id" "name" } { 1 "Paul" 2 "Chani" 3 "Vladimir" } , houses: table { "id" "house" } { 1 "Atreides" 3 "Harkonnen" } , names .inner-join houses 'id 'id |header?
; returns list { "id" "name" "id_2" "house" }

names: table { "id" "name" } { 1 "Paul" 2 "Chani" 3 "Vladimir" } , houses: table { "id" "house" } { 1 "Atreides" 3 "Harkonnen" } , names .left-join houses 'id 'id |column? "name"
; returns { "Paul" "Chani" "Vladimir" }