|
|
Guide | Patterns | Reference | Code |
Copyright © 2025 Ufko (ufko.org)
This manual is released under the MIT license. You may use, copy, modify and distribute it freely, provided that this notice is preserved.
syntax: (! str-shell-command)
Description:
Executes the external command contained in
str-shell-command. The call blocks until the invoked
program terminates. The return value is the exit status
reported by the operating system.
Use exec when capturing standard output or providing
standard input is required. Use process for non-blocking
execution or when redirecting streams through pipes.
A leading ! at the start of a line in the interactive shell is a special operator, not a function call. In that form, parentheses are omitted and the remainder of the line is forwarded directly to the system shell.
Examples:
(! "nvi2")
(! "ls -ltr")
; interactive shell operator form
!ls -ltr
Notes:
syntax: ($ int-idx)
Description:
Provides indexed access to the predefined system variables $0, $1, $2–$15. These variables are assigned by functions that perform regular expression matching or token extraction. Each storing function updates the variables as part of its operation, and the stored values remain available until the next regex-driven call.
The variables may be referenced directly by name or
through numeric indexing with this function. Using ($
int-idx) enables programmatic access when the index is
not known in advance.
Examples:
(set txt "http://example.org:80")
(pos "http://(.*):(.*)" txt 0) ; → 0
$0 ; → "http://example.org:80"
$1 ; → "example.org"
$2 ; → "80"
($ 0) ; → "http://example.org:80"
($ 1) ; → "example.org"
($ 2) ; → "80"
Notes:
($ int-idx) is equivalent to referencing
the variables $0–$15 directly.See: pos, find, rx, replace, parse
syntax: (+ int-1 [int-2 ...])
Description:
Computes the sum of all arguments. Each value is treated as an integer. Floating point arguments are truncated toward zero before the addition. Values exceeding the machine integer limits wrap around after the operation. Arguments evaluating to NaN are treated as zero.
Examples:
(+ 1 2 3 4 5) ; → 15
(+ 1 2 (- 5 2) 8) ; → 14
(+ 1.2 3.9) ; → 4
Notes:
syntax: (- int-1 [int-2 ...])
Description:
Subtracts each subsequent argument from the running result. All arguments are treated as integers. Floating point arguments are truncated toward zero. With a single argument, the sign of that value is reversed. Results that exceed the integer range wrap around. Arguments evaluating to NaN are treated as zero.
Examples:
(- 10 3 2 1) ; → 4
(- (* 3 4) 6 1 2) ; → 3
(- 123) ; → -123
(map - '(10 20 30)) ; → (-10 -20 -30)
Notes:
syntax: (* int-1 [int-2 ...])
Description:
Computes the product of all arguments. Every value is converted to an integer by truncating floating point inputs toward zero. Results that exceed the integer range wrap around. Arguments evaluating to NaN are treated as zero before multiplication.
Examples:
(* 1 2 3) ; → 6
(* 10 (- 8 2)) ; → 60
Notes:
syntax: (/ int-1 [int-2 ...])
Description:
Divides the running result by each subsequent argument. All values are converted to integers by truncating floating point inputs toward zero. Division by zero causes an error. When the result exceeds the integer range, it wraps around. Arguments evaluating to NaN are treated as zero, which triggers a division-by-zero error.
Examples:
(/ 12 3) ; → 4
(/ 120 3 20 2) ; → 1
Notes:
syntax: (% int-1 [int-2 ...])
Description:
Performs successive integer modulo operations. Each
argument is converted to an integer by truncating any
floating point value toward zero. The running result is
replaced by (mod result int-i) for each argument. A
division-by-zero condition raises an error. When the
result exceeds the integer range, it wraps around.
Values evaluating to NaN are treated as zero and cause a
division-by-zero error.
Floating point numbers should be handled with the mod
function instead, which preserves fractional behavior.
Examples:
(% 10 3) ; → 1
(% -10 3) ; → -1
Notes:
mod.syntax: (++ place [num ...])
Description:
Increments the value stored at place using integer
arithmetic. When no num argument is supplied, the value
is increased by 1. When one or more arguments are given,
each value is truncated toward zero before being added
to the running total.
If place refers to a symbol containing nil, it is
treated as if it contained 0. When place refers to a
list position, the element at that position is updated
in place. If place is an expression that yields a
number, the incremented result is returned but not
stored.
All calculations use integer limits. Values exceeding
9,223,372,036,854,775,807 wrap around to negative
numbers. Values smaller than
-9,223,372,036,854,775,808 wrap around to positive
numbers. Arguments evaluating to NaN are treated as 0.
Examples:
(set n 1)
(++ n) ; → 2
(set n 3.8)
(++ n) ; → 4
(++ n 1.3) ; → 5
(set lst '(1 2 3))
(++ (lst 1) 2) ; → 4
lst ; → (1 4 3)
Notes:
nil is treated as 0 when used as a place.inc.syntax: (-- place [num ...])
Description:
Decrements the value stored at place using integer
arithmetic. When no num argument is supplied, the value
is decreased by 1. When additional arguments are given,
each value is truncated toward zero before being
subtracted from the running result.
If place refers to a symbol containing nil, it behaves
as if it contained 0. When place selects an element in a
list, that element is updated in place. If place is an
expression that merely yields a number, the decremented
result is returned but not stored.
All operations use the full integer range. Values that
exceed 9,223,372,036,854,775,807 wrap around to negative
numbers. Values below -9,223,372,036,854,775,808 wrap
around to positive numbers. Arguments evaluating to NaN
are treated as 0.
Examples:
(set n 1)
(-- n) ; → 0
(set n 3.8)
(-- n) ; → 2
(-- n 1.3) ; → 1
(set lst '(1 2 3))
(-- (lst 1) 2) ; → 0
lst ; → (1 0 3)
Notes:
nil is treated as 0 when used as a place.dec.syntax: (< exp-1 [exp-2 ...])
Description:
Evaluates all expressions and compares each pair in
sequence. The result is true only if every comparison
satisfies the < relation. As soon as one comparison
fails, the function returns nil.
With a single argument, the operator compares the value
against 0. This checks whether the number is negative.
All data types can be compared. Lists are compared element by element; earlier elements have higher significance. When lists share all elements but differ in length, the longer list is greater. Mixed types follow a fixed type ordering, and numeric types are converted as needed. Floating point values are truncated toward zero for bigint comparison rules.
Examples:
(< 3 5 8 9) ; → true
(< "a" "c" "d") ; → true
(< '(3 4) '(1 5)) ; → nil
(< '(1 2 3) '(1 2)) ; → nil
(< 1.2 6 "Hello") ; → true
(< nil true) ; → true
(< '(((a b))) '(((b c)))) ; → true
(< '( (a (b c)) '(a (b d)) '(a (b (d))) )) ; → true
; single-argument form (compares with 0)
(< -1) ; → true
(< 1) ; → nil
Notes:
0.nil < true < number < string < symbol < primitive
< quoted list < list < fn < fn-macro.syntax: (> exp-1 [exp-2 ...])
Description:
Evaluates all expressions and compares them in order
using the > relation. The result is true only when every
comparison succeeds. If any comparison fails, evaluation
stops and nil is returned.
With one argument, the value is compared against 0. This checks whether the number is positive.
All types may be compared. Lists are compared element by element; earlier elements have greater significance than later ones. If lists share all compared elements but differ in length, the longer list is considered greater. Mixed-type comparisons follow a fixed type ordering. Floating point values are truncated toward zero for integer comparison.
Examples:
(> 4 2 3 6) ; → nil
(> '(1 2 3) '(1 2)) ; → true
(> 5 1 -3 -9) ; → true
(> "z" "b" "a") ; → true
; single-argument form (compare with 0)
(> 1) ; → true ; positive
(> -1) ; → nil ; not positive
(map > '(1 3 -4 -3 1 2)) ; → (true true nil nil true true)
Notes:
0.nil < true < number < string < symbol < primitive
< quoted list < list < fn < fn-macro.syntax: (= exp-1 [exp-2 ...])
Description:
Evaluates all expressions and compares them pairwise for
equality. The result is true only when each comparison
returns true. If any pair does not match, the function
returns nil.
When called with a single argument, the value is
compared against 0, which allows checking for zero.
Equality applies to all data types. Numbers are compared as integers after truncation toward zero. Strings, symbols, and atoms compare by value. Lists are compared recursively; they are equal only when every element in corresponding positions is equal and both lists have the same length. Mixed-type comparisons follow a fixed precedence when determining ordering, but for equality the types must match after conversion rules.
Examples:
(= '(5 7 8) '(5 7 8)) ; → true
(= 10 10 10) ; → true
(= 3 5) ; → nil
(= "a" "a") ; → true
(= '(1 2) '(1 2 3)) ; → nil
; single-argument form (compare with 0)
(= 0) ; → true
(= 123) ; → nil
Notes:
0.syntax: (<= exp-1 [exp-2 ...])
Description:
Evaluates all expressions and compares each consecutive
pair using the <= relation. The result is true only if
every comparison succeeds. When any comparison fails, the
function returns nil immediately.
With a single argument, the operator compares the value
against 0, allowing a check for “less than or equal to
zero.”
All data types may be compared. Lists compare element-by-element; earlier elements have higher significance. If the lists share all compared elements but differ in length, the shorter list is considered less. Mixed-type comparisons follow a fixed type precedence. Numeric values are compared as integers, with floating point inputs truncated toward zero.
Examples:
(<= 1 2 2 5) ; → true
(<= 5 3 1) ; → nil
(<= '(1 2) '(1 2 3)) ; → true
(<= "a" "b" "b" "z") ; → true
; single-argument form (compare with 0)
(<= 0) ; → true
(<= -3) ; → true
(<= 5) ; → nil
Notes:
0.syntax: (>= exp-1 [exp-2 ...])
Description:
Evaluates all expressions and compares each pair using
the >= relation. The result is true only when every
comparison succeeds. If any comparison fails, evaluation
stops and nil is returned.
With a single argument, the operator compares the value
against 0. This makes it possible to test whether a
number is non-negative.
All data types may be compared. Lists compare recursively: earlier elements have higher significance, and when all elements match but lengths differ, the longer list is considered greater. Mixed-type comparisons follow a fixed precedence. Numeric comparisons follow integer rules, and floating point arguments are truncated toward zero.
Examples:
(>= abcd ab) ; → true
(>= 9 3 3 -1) ; → true
(>= '(1 2 3) '(1 2)) ; → true
(>= "z" "z" "a") ; → true
(>= "a" "b") ; → nil
; single-argument form (compare with 0)
(>= 1) ; → true
(>= 0) ; → true
(>= -1) ; → nil
Notes:
0.syntax: (!= exp-1 [exp-2 ...])
Description:
Evaluates all expressions and checks that each consecutive pair is not equal. The result is true only when every comparison evaluates to inequality. If any pair is equal, the function returns nil.
With a single argument, the operator compares the value against 0. This allows checking whether a value is “not zero.”
Equality rules follow the same semantics as the = operator. Numbers are compared as integers, with floating point values truncated toward zero. Lists compare recursively by structure and length. Mixed-type comparisons follow the general type precedence rules.
Examples:
(!= 1 4 3 7 3) ; → true
(!= 5 5) ; → nil
(!= '(1 2) '(1 2 3)) ; → true
(!= "a" "b" "b") ; → nil
; mixed-type chain
(!= 1 "x" '(1 2) true) ; → true
; single-argument form (compare with 0)
(!= 0) ; → nil
(!= 123) ; → true
Notes:
0.syntax: (<< int-1 int-2 [int-3 ...])
syntax: (<< int-1)
Description:
Performs an arithmetic left shift on int-1. Each shift
argument specifies how many bits to shift. The result of
each step becomes the input to the next. For integers,
the allowed shift distance is up to 63 bits on 64-bit
platforms.
When only one argument is supplied, the value is shifted left by 1 bit. All operations use integer arithmetic, with wrap-around on overflow.
Examples:
(<< 1 3) ; → 8
(<< 1 2 1) ; → 8
(<< 3) ; → 6
Notes:
See: >>
syntax: (>> int-1 int-2 [int-3 ...])
syntax: (>> int-1)
Description:
Performs an arithmetic right shift on int-1. Each shift
argument specifies how many bits to move. The result of
each shift becomes the input to the next. Arithmetic
right shifting duplicates the most significant bit,
preserving the sign of the number.
When only one argument is given, the value is shifted right by 1 bit. Shift distances up to 63 bits are valid on 64-bit platforms. Operations use integer arithmetic with wrap-around on overflow.
Examples:
(>> 1024 10) ; → 1
(>> 160 2 2) ; → 10
(>> 8) ; → 4
; arithmetic shift keeps the sign bit
(>> 0x8000000000000000 1) ; → 0xC000000000000000
Notes:
See: <<
syntax: (& int-1 int-2 [int-3 ...])
Description:
Performs a bitwise AND operation. The value in int-1 is
combined with int-2 using AND, and the result is then
combined with each additional argument in sequence.
All arguments are treated as integers. Floating point inputs are truncated toward zero before the operation. The result always fits in the machine integer range.
Examples:
(& 0xAABB 0x000F) ; → 11 ; 0xB
(& 255 1 1 1) ; → 1
(& 42 63) ; → 42
Notes:
syntax: (| int-1 int-2 [int-3 ...])
Description:
Performs a bitwise OR operation. The value in int-1 is
combined with int-2, and the resulting value is then
combined with each remaining argument in order. All
arguments are converted to integers by truncating
floating point values toward zero.
The operation sets each bit in the result if that bit is set in any of the processed arguments.
Examples:
(| 0x10 0x80 2 1) ; → 147
(| 1 4 16) ; → 21
(| 0 0 7) ; → 7
Notes:
syntax: (^ int-1 int-2 [int-3 ...])
Description:
Performs a bitwise XOR operation. The value in int-1 is
combined with int-2 using XOR, and the resulting value is
then combined with each following argument in sequence.
All arguments are treated as integers, with floating
point values truncated toward zero.
Each bit in the result is set when the corresponding bit is set in an odd number of the processed arguments.
Examples:
(^ 0xAA 0x55) ; → 255
(^ 15 8 7) ; → 0
(^ 42 42) ; → 0
Notes:
syntax: (~ int)
Description:
Performs a bitwise NOT operation on int. All bits in the
integer are inverted. The result is computed using the
full machine integer width. Floating point values are
truncated toward zero before the operation.
Examples:
(format "%X" (~ 0xFFFFFFAA)) ; → "55"
(~ 0xFFFFFFFF) ; → 0
(~ 0) ; → -1
Notes:
syntax: (abort int-pid)
syntax: (abort)
Description:
Terminates child processes created with spawn. In the
first form, abort sends a termination request to the
specific child identified by int-pid. The process must
have been created using spawn. Processes started via
fork are not affected; Function kill must be used for
those.
In the second form, abort terminates all child processes
spawned by the current process. The function returns
true when the requested terminations have been issued.
The abort function is part of the Cilk-style process
coordination interface used for structured parallel
execution.
Examples:
(abort 2245) ; → true ; abort one child
(abort) ; → true ; abort all spawned children
Notes:
fork require kill.syntax: (abs num)
Description:
Returns the absolute value of num. Integer arguments are
processed in bigint mode. Floating point arguments keep
their fractional part. Negative values are converted to
their positive counterparts, while positive values and
zero remain unchanged.
Examples:
(abs -3.5) ; → 3.5
(abs 0) ; → 0
(abs -9223372036854775808) ; → 9223372036854775808
Notes:
See: sgn
syntax: (acos num-radians)
Description:
Computes the arc cosine of num-radians. The argument is
interpreted as a floating point value. The result is the
angle whose cosine equals the input value. The output is
given in radians. Values outside the domain [-1, 1]
produce NaN.
Examples:
(acos 1) ; → 0
(cos (acos 1)) ; → 1
(acos 0) ; → 1.5707963268
Notes:
[-1, 1].syntax: (acosh num-radians)
Description:
Computes the inverse hyperbolic cosine of num-radians.
The result is the value whose hyperbolic cosine equals
the argument. Valid input begins at 1. Values below 1
produce NaN. The return value is a floating point number
expressed in radians.
Examples:
(acosh 2) ; → 1.316957897
(cosh (acosh 2)) ; → 2
(acosh 0.5) ; → NaN
Notes:
[1, +infinity). Values < 1 yield NaN.syntax: (add num-1 [num-2 ...])
Description:
Returns the floating point sum of all arguments. Each value may be an integer or a float, but the result is always a floating point number. The calculation follows normal floating point rules. If any argument evaluates to NaN, the final result is NaN.
Examples:
(add 2 3.25 9) ; → 14.25
(add 1 2 3 4 5) ; → 15
Notes:
syntax: (address int)
syntax: (address float)
syntax: (address str)
Description:
Returns the memory address of the value referenced by
int, float, or str. The returned value is an integer
representing the address of the underlying storage used
by the object.
This function is primarily used when passing pointers to
external C functions imported with import. The returned
address may also be used for pointer arithmetic.
When a string is passed directly as an argument to an imported C function, its address is supplied implicitly and an explicit call to address is not required.
The argument must refer to a value stored in a variable. Addresses of temporary values produced by expressions are not stable and must not be used.
Examples:
(set s "\001\002\003\004")
(charc (+ (address s) 3)) ; → 4
(set x 12345)
(longc (address x)) ; → 12345
(set x 1234567890)
(longc (address x)) ; → 1234567890
Notes:
import.See: charc, intc, longc, floatc
syntax: (alarm sym-event-handler | func-event-handler num-seconds [int-option])
syntax: (alarm sym-event-handler | func-event-handler)
syntax: (alarm)
Description:
Starts or controls a one-shot alarm which invokes a
user-defined event handler after a specified delay.
When called with an event handler and num-seconds,
alarm schedules the handler to be executed after
num-seconds seconds have elapsed. The handler may be
given as a symbol naming a function or as an anonymous
function.
The alarm is implemented using Unix interval timers
and delivers one of the signals SIGALRM, SIGVTALRM, or
SIGPROF depending on the selected mode.
The optional int-option controls how time is measured:
0 real (wall-clock) time (default)
1 process CPU time
2 profiling time (real + CPU)
Seconds may be specified as floating point values, allowing sub-second resolution.
Specifying num-seconds as 0 disables a running alarm
and prevents it from firing.
When called with only an event handler, alarm returns
the elapsed time of the currently running alarm. This
can be used to implement time lines or schedules.
When called without arguments, alarm returns the
symbol of the currently installed event handler.
Examples:
; periodic alarm using re-arming
;------------------------------------------------------------
(func (ticker)
(println (date))
(alarm 'ticker 1.0))
(ticker)
;-> ticker
; alarm events:
; Tue Apr 12 20:44:49 2005
; Tue Apr 12 20:44:50 2005
; Tue Apr 12 20:44:51 2005
Notes:
alarm handler may re-arm the alarm to create
periodic behavior.alarm cannot interrupt a running built-in
function; it runs between expression evaluations.nselect are required.See: nselect
syntax: (and exp-1 [exp-2 ...])
Description:
Evaluates each expression from left to right and returns
the value of the last one. If any expression evaluates
to nil or to the empty list (), evaluation stops
immediately and that value is returned. When called with
no arguments, the result is true.
This operator provides short-circuit behavior: evaluation continues only as long as all intermediate results are non-nil and not ().
Examples:
(set x 10) ; → 10
(and (< x 100) (> x 2)) ; → true
(and (< x 100) (> x 2) "passed") ; → "passed"
(and '()) ; → ()
(and true) ; → true
(and) ; → true
Notes:
nil or ().true.syntax: (append list-1 [list-2 ...])
syntax: (append array-1 [array-2 ...])
syntax: (append str-1 [str-2 ...])
Description:
Builds and returns a new list, array, or string by concatenating all supplied arguments. The original data objects are never modified. The behavior depends on the type of the first argument.
When the first argument is a list, all lists are joined sequentially into a new list. When the first argument is an array, each array’s rows are appended to produce a new array with increased row count. When the first argument is a string, all strings are concatenated into a new string. Binary strings containing zero bytes are preserved accurately.
For linkage characters or custom separators, use join.
Use string to convert values and concatenate in one step.
To modify an existing list or string in place, use extend
or push.
Examples:
(append '(1 2 3) '(4 5 6) '(a b))
; → (1 2 3 4 5 6 a b)
(set lst '("hello" "world"))
(append lst '("here" "I am"))
; → ("hello" "world" "here" "I am")
(set A (array 3 2 (seq 1 6)))
; → ((1 2) (3 4) (5 6))
(set B (array 2 2 (seq 7 10)))
; → ((7 8) (9 10))
(append A B)
; → ((1 2) (3 4) (5 6) (7 8) (9 10))
(append B B B)
; → ((7 8) (9 10) (7 8) (9 10) (7 8) (9 10))
(set more " how are you")
(append "Hello " "world," more)
; → "Hello world, how are you"
Notes:
extend or push.syntax: (apply function list [int-reduce])
syntax: (apply function)
Description:
Invokes function using the elements of list as its
arguments. The function in func may be a primitive,
a user-defined function, or a fn expression. Only
functions that evaluate all of their arguments may be
used; special forms that evaluate selectively (such as
dolist or case) will fail when used with apply.
In the second syntax form, apply simply calls
function without any arguments.
When int-reduce is supplied, it specifies how many
arguments function consumes. The function is then
applied repeatedly in left-associative order: the
result of each application becomes the first argument
of the next application, and the remaining arguments
are taken successively from list. This mechanism
allows a two-argument function to be extended into a
variadic one.
Examples:
(apply + '(1 2 3 4))
; → 10
(set lst '(3 4 5))
(apply * lst)
; → 60
(apply sqrt '(25))
; → 5
(apply (fn (x y) (* x y)) '(3 4))
; → 12
; reduce mode example
(func (gcd_ a b)
(let (r (% b a))
(if (= r 0) a (gcd_ r a))))
(mac (my-gcd)
(apply gcd_ (map eval (args)) 2))
(my-gcd 12 18 6) ; → 6
(my-gcd 12 18 6 4) ; → 2
Notes:
dolist, case, etc.) cannot be used.int-reduce applies function repeatedly in
left-associative order.syntax: (args)
syntax: (args int-idx-1 [int-idx-2 ...])
Description:
Returns all unbound arguments of the currently
executing function or macro. Only arguments not
already matched to formal parameters remain in this
list. The function is useful for defining functions or
macros that accept a variable number of parameters.
For macros, args avoids accidental variable capture
because the returned values belong strictly to the
caller’s context.
When called with one or more indices, args returns
the corresponding elements from the unbound argument
list. Indices may be nested-access indices, allowing
traversal inside structured data such as lists.
Examples:
(mac (print-line)
(dolist (x (args))
(print x "\n")))
(print-line "hello" "World")
; prints each argument on its own line
(mac (m)
(print (args 2) (args 1) (args 0)))
(m x y z)
; → zyx
(func (f)
(args 0 2 -1))
(f '(1 2 (3 4)))
; → 4
; bound vs unbound arguments
(func (f a b)
(args))
(f 1 2)
; → ()
(f 1 2 3 4 5)
; → (3 4 5)
Notes:
(args) inside a macro and passing it as an
argument to another macro is invalid, because args
would not be evaluated in the target macro’s
environment.syntax: (array int-n1 [int-n2 ...] [list-init])
Description:
Creates an array with int-n1 elements. Additional
integer dimensions define a multidimensional array,
supporting up to sixteen dimensions. When list-init
is supplied, its elements initialize the array. If
list-init has fewer elements than required, its
contents repeat until all array positions are filled.
Elements may be of any type.
Multidimensional arrays are stored as arrays of arrays. Arrays provide efficient random indexing compared to lists. Most list operations work on arrays, but not all; details depend on the specific function. Replacing whole rows requires care to ensure the replacement itself is an array and not a list.
Arrays can be converted to lists using arraylist, and
lists can be converted back by flattening them with
flat before constructing a new array.
Serialization using save or source preserves array
structure by writing the necessary array expression.
Examples:
(array 5)
; → (nil nil nil nil nil)
(array 5 (seq 1 5))
; → (1 2 3 4 5)
(array 10 '(1 2))
; → (1 2 1 2 1 2 1 2 1 2)
(set a (array 3 4 (seq 1 12)))
; → ((1 2 3 4) (5 6 7 8) (9 10 11 12))
(set (a 2 3) 99)
; → 99
a
; → ((1 2 3 4) (5 6 7 8) (9 10 11 99))
(set (a 1 1) "hello")
a
; → ((1 2 3 4) (5 "hello" 7 8) (9 10 11 99))
(set (a 1) '(a b c d))
a
; → ((1 2 3 4) (a b c d) (9 10 11 99))
(nth 1 a)
; → (a b c d)
; array indexing and slicing
(a 1)
; → (a b c d)
(a 0 -1)
; → 4
(2 a)
; → ((9 10 11 99))
(-3 2 a)
; → ((1 2 3 4) (a b c d))
(arraylist a)
; → ((1 2 3 4) (a b c d) (1 2 3 99))
(set lst '((1 2) (3 4)))
(set arr (array 2 2 (flat lst)))
; → ((1 2) (3 4))
(array? a)
; → true
(array? (arraylist a))
; → nil
; serialization example
(set a (array 3 4 (seq 1 12)))
(save "array.rbl" 'a)
;; saved file includes array expression
Notes:
list-init repeats until the array is fully initialized.arraylist converts arrays to lists; flat assists in
reconstructing arrays from list data.syntax: (arraylist array)
Description:
Converts an array into a list structure. The conversion
is recursive: every row of a multidimensional array is
turned into a list, and nested arrays become nested
lists. The original array is left unchanged.
Examples:
(set a (array 3 4 (seq 1 12)))
; → ((1 2 3 4) (5 6 7 8) (9 10 11 12))
(set lst (arraylist a))
; → ((1 2 3 4) (5 6 7 8) (9 10 11 12))
(list (array? a) (list? lst))
; → (true true)
Notes:
syntax: (array? exp)
Description:
Checks whether exp is an array. The function returns true
when the expression is an array object and nil otherwise.
Nested or converted list structures do not qualify as
arrays, even when their shape resembles one.
Examples:
(set M (array 3 4 (seq 1 4)))
; → ((1 2 3 4) (1 2 3 4) (1 2 3 4))
(array? M)
; → true
(array? (arraylist M))
; → nil
Notes:
arraylist are not
arrays.syntax: (asin num-radians)
Description:
Computes the arcsine of num-radians and returns the
result as a floating point value in radians. The input
must lie within the domain [-1, 1]. Values outside this
range return NaN. The output is the angle whose sine
equals the argument.
Examples:
(asin 1) ; → 1.570796327
(sin (asin 1)) ; → 1
Notes:
[-1, 1]. Outside values produce NaN.syntax: (asinh num-radians)
Description:
Computes the inverse hyperbolic sine of num-radians and
returns the floating point result in radians. The value
represents the number whose hyperbolic sine equals the
input. All real values are valid; the function has no
domain restrictions.
Examples:
(asinh 2) ; → 1.443635475
(sinh (asinh 2)) ; → 2
Notes:
sinh.syntax: (assoc exp-key list-alist)
syntax: (assoc list-exp-key list-alist)
Description:
Searches an association list for an entry whose first
element matches the given key. In the first form,
exp-key is a single key expression. The function
scans each member-list of list-alist; when the first
element equals exp-key, that member-list is returned.
If no match is found, the result is nil.
In the second form, list-exp-key is a list of keys
used to traverse nested association lists. Each key
selects a sublist, allowing lookup inside multilevel
structures.
When list-alist is a context symbol, assoc operates
on its default functor, enabling large association
lists to be referenced without copying.
assoc may be combined with set to modify association lists in place.
Examples:
(assoc 1 '((3 4) (1 2)))
; → (1 2)
(set db '((kiwi 12) (mango 77 5) (plum 9)))
(assoc 'mango db)
; → (mango 77 5)
(assoc 'papaya db)
; → nil
; modifying an association
(set (assoc 'plum db) '(plum 10))
db
; → ((kiwi 12) (mango 77 5) (plum 10))
; nested association lists
(set records '(
(u001 (name "Nora")
(address (country "Japan") (city "Kyoto")))
(u002 (name "Liam")
(address (country "Brazil") (city "Recife")))
))
(assoc '(u001 address) records)
; → (address (country "Japan") (city "Kyoto"))
(assoc '(u001 address city) records)
; → (city "Kyoto")
; using a context as the association list
(set people:people '(
(u001 (name "Nora")
(address (country "Japan") (city "Kyoto")))
(u002 (name "Liam")
(address (country "Brazil") (city "Recife")))
))
(func (get-city db id)
(last (assoc (list id 'address 'city) db)))
(get-city people 'u001)
; → "Kyoto"
Notes:
assoc returns the full matching pair or sublist.list-exp-key allows multilevel lookup.assoc operates on the
context’s default functor.assoc with set.lookup provides lookup + extraction in one step.syntax: (atan num-radians)
Description:
Computes the arctangent of num-radians and returns the
result as a floating point value in radians. The output
is the angle whose tangent equals the input. All real
values are valid; the function has no domain
restrictions.
Examples:
(atan 1) ; → 0.7853981634
(tan (atan 1)) ; → 1
Notes:
syntax: (atan2 num-Y-radians num-X-radians)
Description:
Computes the arctangent of Y / X while using the signs of both arguments to determine the correct quadrant of the result. The return value is a floating point angle in radians. Unlike atan, which cannot distinguish between opposite quadrants, atan2 provides the full range (-π, π], making it suitable for converting Cartesian coordinates to polar form.
Examples:
(atan2 1 1) ; → 0.7853981634
(div (acos 0) (atan2 1 1)) ; → 2
(atan2 0 -1) ; → 3.141592654
(= (atan2 1 2) (atan (div 1 2))) ; → true
Notes:
syntax: (atanh num-radians)
Description:
Computes the inverse hyperbolic tangent of num-radians.
The result is the value whose hyperbolic tangent equals
the input. The valid domain is [-1, 1]. Inputs with an
absolute value greater than 1 produce NaN. An-value ±1
returns positive or negative infinity, respectively.
Examples:
(atanh 0.5) ; → 0.5493061443
(tanh (atanh 0.5)) ; → 0.5
(atanh 1.1) ; → NaN
(atanh 1) ; → inf
Notes:
syntax: (atom? exp)
Description:
Checks whether exp evaluates to an atom. An expression is
considered an atom if it evaluates to one of the
following: nil, true, an integer, a float, a string, a
symbol, or a primitive. Structures such as lists,
fn expressions, fn-macro expressions, and quoted
lists are not atoms.
Examples:
(atom? '(1 2 3))
; → nil
(and (atom? 123)
(atom? "hello")
(atom? 'foo))
; → true
(atom? ''foo)
; → nil
Notes:
atom? tests the evaluated expression, not its literal
form.syntax: (b64dec str)
Description:
Decodes the BASE64-encoded string in str and returns the
decoded byte sequence as a string. The input is not
validated for correctness; invalid or malformed BASE64
data may yield unspecified output. The implementation is
compatible with RFC 4648 and is derived from routines
used in Unix curl.
Examples:
(b64dec "SGVsbG8gV29ybGQ=")
; → "Hello World"
Notes:
See: b64enc
syntax: (b64enc str [bool-flag])
Description:
Encodes str into BASE64 format. BASE64 groups input bytes
in sets of three (24 bits) and produces four encoded
bytes (32 bits). Each 6-bit segment maps to one of 64
characters: A–Z, a–z, 0–9, +, and /. The character = is
used as padding when the input does not align to 3-byte
blocks. The result is a printable representation suitable
for embedding binary data in text-oriented formats.
When bool-flag is omitted or nil, the empty string ““
is encoded as “====”. When bool-flag is true, the empty
string encodes to ““. Both encodings decode back to ““
using b64dec.
The function returns the encoded string. No line breaks are inserted; the result is a continuous BASE64 sequence. The implementation conforms to RFC 4648 and is derived from Unix curl routines.
Examples:
(b64enc "Hello World")
; → "SGVsbG8gV29ybGQ="
(b64enc "")
; → "===="
(b64enc "" true)
; → ""
Notes:
bool-flag.See: b64dec
syntax: (bigint number)
syntax: (bigint string)
Description:
Converts a number or a numeric string into a big integer.
Floating point inputs are converted by truncating toward
zero after binary-to-decimal transformation, which may
introduce rounding artifacts. Integer inputs convert
exactly.
When the argument is a string, it is parsed from the beginning until a non-numeric character appears. The parsed part is then converted into a big integer. A decimal point ends numeric parsing, so only the integer portion is used.
The result is returned in big integer format, marked with
an L suffix when printed.
Examples:
(bigint 12345)
; → 12345L
(bigint 1.234567890e30)
; → 1234567889999999957361000000000L
(set n 567890)
(bigint n)
; → 567890L
(bigint "-54321")
; → -54321L
(bigint "123.45")
; → 123L
(bigint "123hello")
; → 123L
Notes:
syntax: (bind list-variable-associations [bool-eval])
Description:
Takes an association list of symbol–value pairs and
assigns each symbol its corresponding value. When
bool-eval is omitted or nil, the values are assigned
exactly as they appear. When bool-eval is true, each
value is evaluated before assignment.
The return value of bind is the value of the last association in the list.
bind is commonly used together with unify, which
produces association lists suitable for destructuring.
Examples:
(set lst '((a (+ 3 4)) (b "hello")))
(bind lst)
; → "hello"
a ; → (+ 3 4)
b ; → "hello"
(bind lst true)
; → "hello"
a ; → 7
; using bind with unify
(bind (unify '(p X Y a) '(p Y X X)))
; → a
X ; → a
Y ; → a
; destructuring example
(set structure '((one "two") 3 (four (x y z))))
(set pattern '((A B) C (D E)))
(bind (unify pattern structure))
A ; → one
B ; → "two"
C ; → 3
D ; → four
E ; → (x y z)
Notes:
bool-eval = true, values are evaluated first.unify for de-structuring patterns.syntax: (bits int [bool])
Description:
Converts an int into either a binary string or a list
of bit values. When bool is omitted or nil, the result is
a string of '1' and '0' characters, ordered from the
most significant bit to the least significant bit.
When bool evaluates to anything non-nil, bits returns a
list of booleans representing the binary form of the
integer, ordered from the lowest bit to the highest bit:
true for bit value 1 and nil for bit value 0. This
ordering allows direct indexing and use in flow control.
The function int with base 2 is the inverse of bits.
Examples:
(bits 1234)
; → "10011010010"
(int (bits 1234) 0 2)
; → 1234
(bits 1234 true)
; → (nil true nil nil true nil true true nil nil true)
((bits 1234 true) 0)
; → nil
Notes:
int with base 2 reverses bits back to the integer.syntax: (callback int-index sym-function)
syntax: (callback sym-function str-return-type [str-param-type ...])
syntax: (callback sym-function)
Description:
Creates a C-callable function pointer which invokes the
Rebel function stored in sym-function. The mechanism
supports two independent modes. In the simple form the
first parameter selects one of sixteen static callback
slots numbered 0 to 15. Each slot contains a built-in
C function which transfers control into the runtime.
Assigning sym-function to a slot causes external C code
calling the slot pointer to enter the Rebel evaluator
and run the assigned function. This simple form accepts
up to eight parameters as raw integer or pointer
values. The slot pointer remains valid until reassigned
with a new sym-function.
The extended syntax uses libffi closures. A closure is
allocated dynamically and configured with a call
interface describing the return type and parameter
types. When external C code calls the closure address,
libffi performs type conversions, constructs a Rebel
argument list and invokes sym-function. After the
function finishes, libffi converts the returned value
back to the declared C type. This form has no slot
limits and can represent any combination of integer,
floating point or pointer parameters. Pointer values
arriving from C are represented as numbers and may be
inspected using intc, longc or stringc as
needed for buffer access.
The third syntax retrieves the previously created
callback pointer for sym-function. This avoids building
additional closures when the same pointer must be
passed to multiple C functions.
Both simple and extended forms coexist. The first form is useful when a fixed stable pointer is required without allocating new closures. The extended form is used when precise type information is needed, or when a large number of callback functions must be created.
Examples:
;; Simple syntax using slot 0
(func (hello)
;; External C code calling the slot pointer
;; will print this string.
"hello world")
(set p0 (callback 0 'hello))
;; p0 now contains a C-callable pointer. Any C
;; function which receives p0 and calls it will
;; execute (hello).
;; Extended syntax with typed parameters
(func (sum a b)
(+ a b))
(set ps (callback 'sum "int" "int" "int"))
;; ps is a dynamically created libffi closure
;; which accepts two integers and returns an
;; integer result.
Notes:
See: import, intc, longc, pack, unpack
syntax: (cap list-A list-B)
syntax: (cap list-A list-B bool)
Description:
Computes the intersection of list-A and list-B. In the
first form, the result contains one copy of each value
that appears in both lists, preserving the order in
which those values first occur in list-A. Duplicates in
either input list are ignored in this mode.
In the second form, when bool evaluates to true (any
non-nil value), duplicates from list-A are preserved.
Every element of list-A that is also present in list-B
is included in the result in its original order, and no
deduplication occurs.
Membership tests follow standard list element equality.
Examples:
(cap '(3 0 1 3 2 3 4 2 1) '(1 4 2 5))
;-> (2 4 1)
(cap '(3 0 1 3 2 3 4 2 1) '(1 4 2 5) true)
;-> (1 2 4 2 1)
Notes:
list-A.list-A.syntax: (case exp-switch (exp-1 body-1) [(exp-2 body-2) ... ])
Description:
Evaluates exp-switch, then compares its value against
each clause expression. Clause expressions are not
evaluated; they are matched literally. When a match is
found, all forms in the matching body are evaluated in
sequence, and the value of the final form becomes the
result of the case expression. If none of the clause
values match exp-switch, the body of the last clause is
executed and serves as a default branch.
Examples:
(func (translate n)
(case n
(1 "one")
(2 "two")
(3 "three")
(4 "four")
(true "Can't translate this")))
(translate 3) → "three"
(translate 10) → "Can't translate this"
syntax: (catch exp symbol)
syntax: (catch exp)
Description:
Evaluates exp under a handler capable of intercepting
throws and runtime errors. In the first syntax catch
returns a status flag and stores the outcome of exp in
symbol. When evaluation finishes normally, catch
returns true and symbol receives the value of exp. When
a runtime error occurs, catch returns nil and symbol is
set to the formatted error message. When a throw is
triggered during evaluation, catch returns true and
symbol receives the argument supplied to throw. This
form is used when errors or explicit throws are part of
normal program flow and must be handled without aborting
the surrounding computation.
In the second syntax catch returns the normal value of
exp, or if a throw is executed during evaluation—the
argument passed to throw. All intermediate evaluation
frames are discarded and control jumps directly to the
catch expression. This form is commonly used for
breaking out of nested iteration or forcing an early
return from functions or expression blocks.
Both forms install a temporary handler active only for the dynamic extent of exp.
Examples:
(catch (repeat (x 1000)
(if (= x 500) (throw x)))) → 500
(func (f x)
…
(if condition (throw 123))
…
456)
(catch (f p)) → 123 ;; condition true
(catch (f p)) → 456 ;; condition false
(catch (f1 3 4) 'result) → nil
result
→ "ERR: invalid function (symbol) in function catch : (f1 3 4)"
(alias 'f1 +)
(catch (f1 3 4) 'result) → true
result → 7
(catch (repeat (x 100)
(if (= x 50) (throw "fin"))) 'result) → true
result → "fin"
See: throw, throwerror, errorevent
syntax: (ceil number)
Description:
Returns the smallest integer value not less than number.
The result is returned as a floating-point value. When
number is already an integer value, it is returned
unchanged. Negative arguments are rounded upward toward
zero, positive arguments are rounded upward away from
zero.
Examples:
(ceil -1.5) → -1
(ceil 3.4) → 4
See: floor
syntax: (char str [int-index [true]])
syntax: (char int)
Description:
Extracts a character from a string or constructs a
single-character string from an integer code. When the
first argument is a string, char selects the character
at int-index and returns its numeric code. If
int-index is omitted, index 0 is used. Negative indexes
address positions from the end of the string. On UTF-8
enabled builds the index normally refers to logical
UTF-8 characters. When the optional true flag is
supplied, the string is treated as a raw byte array and
the index refers to an 8-bit byte offset.
An empty string yields nil. Both (char 0) and
(char nil) return the single byte string “\000”.
When the first argument is an integer, char returns a
string containing the character with that code. On
UTF-8 enabled builds the integer is interpreted as a
Unicode code point and a UTF-8 encoded character is
returned.
Examples:
(char "ABC") → 65
(char "ABC" 1) → 66
(char "ABC" -1) → 67
(char "B") → 66
(char "Ω") → 937
(char "Ω" 1 true) → 169
(char 65) → "A"
(char 66) → "B"
(char (char 65)) → 65
(map char (seq 1 255))
(char (& (char "生") (char "死"))) → 愛
syntax: (chop str [int-chars])
syntax: (chop list [int-elements])
Description:
Returns a copy of the given string or list with the
specified number of elements removed from the end. When
the first argument is a string, chop omits the last
int-chars characters and returns the shortened copy. If
int-chars is omitted, one character is removed. The
original string is not modified. On UTF-8 enabled
builds character counting refers to logical UTF-8
characters.
When the first argument is a list, chop returns a
shallow copy of the list with int-elements removed from
the end. If int-elements is omitted, one element is
removed. The original list remains unchanged.
Examples:
(set str "Rebelion") → "Rebelion"
(chop str) → "Rebelio"
(chop str 2) → "Rebeli"
str → "Rebelion"
(set lst '(a b (c d) e))
(chop lst) → (a b (c d))
(chop lst 2) → (a b)
lst → (a b (c d) e)
syntax: (clean exp-predicate list)
Description:
Applies exp-predicate to each element of list and
returns a new list containing only those elements for
which the predicate evaluates to false. Elements for
which the predicate returns true are removed. The
behavior is equivalent to using filter with a negated
predicate. The predicate may be any built-in test,
user-defined function or fn expression. The order
of elements is preserved in the returned list.
Examples:
(clean symbol? '(1 2 d 4 f g 5 h)) → (1 2 4 5)
(filter symbol? '(1 2 d 4 f g 5 h)) → (d f g h)
(func (big? x) (> x 5)) → (fn (x) (> x 5))
(clean big? '(1 10 3 6 4 5 11)) → (1 3 4 5)
(clean <= '(3 4 -6 0 2 -3 0)) → (3 4 2)
(clean (curry match '(a *)) '((a 10) (b 5) (a 3) (c 8) (a 9)))
→ ((b 5) (c 8))
syntax: (cline)
Description:
Returns the string most recently read by readln. This
value is also used implicitly by writeln when no
explicit string argument is supplied. cline is
useful for implementing streaming text filters that
process input line by line.
Examples:
; Displays all lines beginning with ";;" from the given
; file.
#!/usr/bin/env rebel
(set f (open (argv 2) "read"))
(while (readln f)
(if (starts? (cline) ";;")
(writeln)))
(exit)
Notes:
See: readln, writeln, argv, starts?
syntax: (clone context-source sym-context-target [bool])
syntax: (clone context-source)
Description:
Copies all symbols and user-defined functions from
context-source into a target context.
When sym-context-target is provided, the context
referenced by context-source is copied into the
target context. If the target context does not exist,
it is created with the same symbol names and
user-defined functions as in context-source.
If the target context already exists, symbols from
context-source are merged into it. Existing symbols
are overwritten only when the optional bool argument
evaluates to anything other than nil. When bool is nil
or omitted, existing symbols in the target context
remain unchanged. This allows controlled mixins of
context objects.
clone returns the target context. The target context
must not be MAIN.
In the second syntax form, the context referenced by
context-source is copied into the current context,
which becomes the implicit target.
During copying, all symbol references that originally pointed into the source context are rewritten so they point into the target context. As a result, all functions and data structures continue to work unchanged, but now operate entirely within the destination context.
Examples:
(context 'ctx1)
;-> ctx1
(context MAIN)
;-> MAIN
(clone ctx1 'ctx2)
;-> ctx2
; force overwrite of existing symbols
(context 'ctx3)
;-> ctx3
(clone ctx1 'ctx3 true)
;-> ctx3
The first example creates a new context ctx2 with the
same structure as ctx1. The source context ctx1 is not
quoted because contexts evaluate to themselves. The
target context ctx2 must be quoted because it does not
exist yet.
The second example merges ctx1 into an existing context
ctx3. Becausectx3already exists, the quote may be
omitted. All symbols of the same name inctx3` are
overwritten.
Contexts may also be referenced indirectly through variables:
(set ctx1:x 123)
(set ctx2:y 999)
(set src ctx1)
(set dst ctx2)
(clone src dst)
;-> ctx2
ctx2:x
;-> 123
ctx2:y
;-> 999
In this example, the context referenced by src (ctx1)
is merged into the context referenced by dst (ctx2).
Notes:
clone copies entire contexts; use clonesym to copy
individual symbols only.bool argument evaluates to non-nil.syntax: (clonesym sym-context-source [sym-context-target])
Description:
Creates a new symbol by copying the definition and
contents of sym-context-source. Only the referenced symbol
is copied; the source context itself is not duplicated.
When sym-context-target is omitted, a symbol of the
same name is created in the current context. In this
case, all symbol references belonging to the source
context are rewritten so they point into the current
context. The current context must not be MAIN.
When sym-context-target is provided, the new symbol
is created in the context referenced by
sym-context-target. Both the name and the
destination context may change. Any symbol reference
that originally pointed into the source context is
rewritten to point into the target context. clonesym
returns the newly created symbol.
This mechanism allows fine-grained copying of functions, data structures, or context members, and enables creation of isolated, statically scoped functions by assigning each copy to its own namespace.
Examples:
(set ctx1:var '(ctx1:x ctx1:y))
;-> (ctx1:x ctx1:y)
(clonesym 'ctx1:var 'ctx2:myvar)
;-> ctx2:myvar
ctx2:myvar
;-> (ctx2:x ctx2:y)
; clonesym into current context
(context 'ctx3)
;-> ctx3
(clonesym 'ctx1:var)
;-> var
var
;-> (x y)
Creating a function with its own namespace:
(set temp (fn (x) (+ x x)))
;-> (fn (x) (+ x x))
(clonesym 'temp 'double:double)
;-> double:double
(double 10)
;-> 20
double:double
;-> (fn (double:x) (+ double:x double:x))
Building a helper for statically scoped accumulators:
(func (func-static s body)
(clonesym 'body (sym s s)))
(func-static 'acc (fn (x)
(inc sum x)))
(acc 1)
;-> 1
(acc 1)
;-> 2
(acc 8)
;-> 10
Notes:
clonesym copies one symbol only; use clone to copy an
entire context.See: clone, context, sym, func
syntax: (close int-file)
Description:
Closes the file or device associated with int-file. The
value in int-file must be a file handle previously
obtained from an open operation or from device. When
the close operation succeeds, the function returns
true; if the handle is invalid or the operation fails,
nil is returned. Closing the device handle resets it to
0, restoring the screen device as the active output
target.
Examples:
(close (device)) → true
(close 7) → true
(close handle) → true
See: open, read, write, device
syntax: (collect exp [int-max-count])
Description:
Repeatedly evaluates exp and accumulates each non-nil
result into a list. Evaluation continues until exp
returns nil, which terminates the collection, or until
int-max-count elements have been gathered when the
optional limit is specified. Each iteration reevaluates
exp from scratch, and all collected values are appended
to the result list in the order produced. If the first
evaluation of exp yields nil, an empty list is
returned.
Examples:
(set x 0)
(collect (if (<= (inc x) 10) x))
→ (1 2 3 4 5 6 7 8 9 10)
(set x 0)
(collect (if (<= (inc x) 10) x) 6)
→ (1 2 3 4 5 6)
syntax: (commandevent sym-event-handler)
syntax: (commandevent func-event-handler)
syntax: (commandevent nil)
Description:
Installs a user-defined handler which receives each
command line before it is evaluated. The handler must
return a string. The returned string becomes the line
executed by the interpreter. Returning the empty string
prints a prompt without evaluating any expression.
Passing nil removes the currently installed handler.
The handler may be a symbol naming a function or a
fn expression. In interactive mode the handler can
rewrite, filter or suppress input lines before they
reach the evaluator, allowing full customization of
REPL input behavior. In http mode (enabled with the
-http option) the handler receives the raw HTTP request
line and may normalize, rewrite or block requests
before they are dispatched to the built-in HTTP
processor. Any non-string return value leaves the
original input line unchanged.
Examples:
;; treat plain words as shell commands
(commandevent
(fn (s)
(if (starts? s "[a-zA-Z]" 0)
(append "!" s)
s)))
;; set a prompt and add simple command translation
(promptevent
(fn (ctx)
(append (dirpath) "> ")))
(commandevent
(fn (s)
(if
(starts? s "cd")
(string " " (true? (dircd (last (parse s " ")))))
(starts? s "[a-zA-Z]" 0)
(append "!" s)
true s)))
Examples (http mode):
;; httpd-conf.rbl
;; filter and rewrite HTTP request lines in -http mode
;; block access to *.ext resources
(commandevent
(fn (s)
(let (request s)
(when (find "?" s)
(set request (first (parse s "?")))
(when (ends? request ".ext")
(set request "GET /forbidden.html")) )
request)))
;; Running:
;; rebel httpd-conf.rbl -http -d80 -w ./httpdoc
;;
;; Incoming:
;; GET /secret.ext?user=abc
;;
;; Translated to:
;; GET /forbidden.html
Notes:
See: promptevent
syntax: (cond (exp-condition-1 body-1) [(exp-condition-2 body-2) ... ])
Description:
Evaluates each exp-condition in order until one of them
yields a value other than nil or the empty list. When a
condition succeeds, its corresponding body is evaluated
and the resulting value becomes the value of the entire
cond expression. If a body is omitted, the value of the
successful exp-condition is returned. When no condition
succeeds, the value of the last evaluated conditional
expression is returned, which is typically nil or an
empty list.
cond is used for multi-branch conditional evaluation. It
behaves like a generalized form of if. When several
conditions must be tested in sequence, cond avoids
nested if forms and allows compact expression of
multiple branches. If used with several condition/body
pairs, the function if behaves similarly but requires no
extra parentheses around each pair.
Examples:
(func (classify x)
(cond
((< x 0) "negative")
((< x 10) "small")
((< x 20) "medium")
((>= x 30) "big")))
(classify 15) → "medium"
(classify 22) → "nil"
(classify 100) → "big"
(classify -10) → "negative"
(cond ((+ 3 4))) → 7
syntax: (cons exp-1 exp-2)
Description:
Creates a new list by combining the values of exp-1 and
exp-2. When exp-2 evaluates to a list, its elements are
prefixed with the value of exp-1. When exp-2 evaluates
to anything other than a list, a two-element list is
constructed from the evaluated arguments. The function
never produces dotted pairs; combining two non-list
values always yields a proper list.
If exp-2 is nil, the result is a list whose first element
is the value of exp-1 and whose second element is nil.
When called with a single argument, cons produces a list
containing that argument. When called without arguments,
it returns an empty list. The operation is effectively
the inverse of extracting the head and tail of a list
using first and rest; when a list has exactly two
elements, first and last form the corresponding pair.
Examples:
(cons 'a 'b) → (a b)
(cons 'a '(b c)) → (a b c)
(cons (+ 3 4) (* 5 5)) → (7 25)
(cons '(1 2) '(3 4)) → ((1 2) 3 4)
(cons nil 1) → (nil 1)
(cons 1 nil) → (1 nil)
(cons 1) → (1)
(cons) → ()
(cons (first '(a b c)) (rest '(a b c))) → (a b c)
(cons (first '(x y)) (last '(x y))) → (x y)
syntax: (const sym-1 exp-1 [sym-2 exp-2] ...)
Description:
Assigns values to symbols and marks those symbols as
protected. A protected symbol cannot be modified. any
attempt to overwrite it raises an error. A protected
symbol can only be changed by calling const again.
Only symbols in the current context may be protected,
preventing accidental changes to names defined in other
contexts. The last initializer expression is optional.
Symbols created with set, func or mac can be
protected retroactively by using const on them. Since
a function definition is internally just an assignment
of a fn value to a symbol, protecting a function name
behaves the same way as protecting a variable.
The final value assigned by const is returned as the
result of the call.
Examples:
(const 'var 123) → 123
(set var 999)
ERR: symbol is protected in function set: var
(func (double x) (+ x x))
(const 'double)
;; equivalent to
(const 'double (fn (x) (+ x x)))
(const 'squareroot sqrt) → sqrt <406C2E>
(const '+ add) → add <4068A6>
Notes:
const.const incurs no
performance penalty. The displayed hexadecimal address
is the internal pointer to the function.syntax: (context [sym-context])
syntax: (context sym-context str|sym [exp-value])
Description:
Switches the current namespace to sym-context. Any
symbols created by evaluating expressions, loading
source files or using evalstr are placed into the
active context. When the context does not yet exist, it
is created. Calling context without arguments returns
the currently active context. Because context symbols
evaluate to themselves, an existing context may be
activated without quoting.
Symbols inside the active context are referenced by their plain names. Symbols in other contexts are accessed using the prefix context-name followed by a colon. Assignments may target symbols in any context using the same prefix form. A symbol reference using a context prefix implicitly creates the context if it does not yet exist.
Contexts can be copied with clone. The copy behaves as an
independent namespace whose symbols can be accessed
directly or by a variable holding a reference to that
context.
In the second syntax, context creates or updates a
symbol inside sym-context without switching to it. This
form acts as namespace-based key/value storage. It does
not change the active context and should not be used as
a general hash mechanism.
Examples:
;; create and switch to GRAPH
(context 'GRAPH)
(func (draw x y) (+ x y))
(set value 123)
(symbols) → (draw value)
;; switch back to MAIN
(context MAIN)
GRAPH:value → 123
(GRAPH:draw 2 3) → 5
(set GRAPH:value 999)
GRAPH:value → 999
;; implicit context creation
(set person:age 0)
(set person:address "")
person:age → 0
;; copy a context
(clone person 'JohnDoe) → JohnDoe
(set JohnDoe:age 99)
JohnDoe:age → 99
;; refer to a context through a variable
(set human JohnDoe)
human:age → 99
(set human:address "1 Main Street")
JohnDoe:address → "1 Main Street"
;; switching using an evaluated context
(context 'ctxA)
(context MAIN)
(set old ctxA)
(context 'ctxB)
(context MAIN:old) → ctxA
;; second syntax: store values in a namespace without switching
(context 'Cfg "mode" "debug") → "debug"
(context 'Cfg 'level 3) → 3
Cfg:mode → "debug"
Cfg:level → 3
Notes:
syntax: (context? exp)
syntax: (context? exp str-sym)
Description:
Predicate for testing context values. In the first
syntax, context? returns true only when exp evaluates to
a context; otherwise it returns nil.
In the second syntax, exp must evaluate to a context.
The function then checks whether a symbol named str-sym
exists inside that context. The symbol name must be
given as a string. The result is true when the symbol is
present and nil when it is absent.
Examples:
;; test for context value
(context? MAIN) → true
(set x 123)
(context? x) → nil
;; implicit context creation and referencing
(set data:msg "hello")
(context? data) → true
(set ctx data)
(context? ctx) → true
;; test for symbol existence inside a context
(context? data "msg") → true
(context? data "xy") → nil
Notes:
str-sym; it must be
a literal symbol name given as a string.syntax: (copy exp)
syntax: (copy int-addr [bool-flag])
Description:
Creates a new independent value from the evaluation of
exp. Some functions modify their arguments in place,
changing the original list, array, or string. Wrapping
the argument with copy forces these functions to operate
on a duplicate, leaving the source data unchanged. The
returned value is the modified duplicate, while the
original stays intact.
A second form exists for low-level interop. When
bool-flag is true, int-addr is treated as a pointer to a
Rebel expression stored in memory. copy retrieves a full
duplicate of that expression. This mode is useful for
bridging external C routines that construct Rebel data in
native memory and expose only an address. The duplicate
behaves as a normal Rebel value and does not reference
the original memory block.
Examples:
(set lst '(a b c d e f)) ;-> (a b c d e f)
(replace 'c (copy lst)) ;-> (a b d e f)
lst ;-> (a b c d e f)
(set str "rebel-lang") ;-> "rebel-lang"
(rot (copy str)) ;-> "grebel-lan"
str ;-> "rebel-lang"
(set x "hello world") ;-> "hello world"
(copy x) ;-> "hello world"
(copy (first (dump x)) true) ;-> "hello world"
syntax: (cos num-radians)
Description:
Computes the cosine of num-radians and returns the
floating-point result. The argument is interpreted as an
angle in radians. The function accepts any real number
and produces a value in the range -1 to 1.
Examples:
(cos 1) ;-> 0.5403023059
(set pi (mul 2 (acos 0))) ;-> 3.141592654
(cos pi) ;-> -1
syntax: (cosh num-radians)
Description:
Computes the hyperbolic cosine of num-radians. The
mathematical definition is (exp x + exp -x) / 2. The
result is always positive and grows rapidly for large
inputs. Extremely large arguments may overflow and return
inf.
Examples:
(cosh 1) ;-> 1.543080635
(cosh 10) ;-> 11013.23292
(cosh 1000) ;-> inf
(= (cosh 1) (div (add (exp 1) (exp -1)) 2))
;-> true
syntax: (crc32 str-data)
Description:
Computes a 32-bit CRC (Cyclic Redundancy Check) value for
the bytes contained in str-data. The calculation starts
with an initial CRC of 0xffffffff and processes each byte
using the standard polynomial method published by w3.org.
The result is an unsigned 32-bit integer suitable for
basic integrity checks.
CRC values are typically used to detect corruption in data streams, files, or network transfers where the data source is not considered fully reliable.
Examples:
(crc32 "abcdefghijklmnopqrstuvwxyz")
;-> 1277644989
See: fread
syntax: (curry function exp)
Description:
Creates a new single-argument function by fixing the
first argument of a two-argument function. curry does not
evaluate function or exp when it is called. Instead, both are
captured and evaluated later when the resulting function
is invoked. The transformation turns a function f(x,y)
into a new function g(y) that behaves like f(exp, y).
This mechanism is useful for building specialized
predicates, filters, and mapping functions without
creating explicit fn expressions.
Examples:
(set f (curry + 10))
;-> (fn ($x) (+ 10 $x))
(f 7)
;-> 17
(filter (curry match '(a *))
'((a 10) (b 5) (a 3) (c 8) (a 9)))
;-> ((a 10) (a 3) (a 9))
(clean (curry match '(a *))
'((a 10) (b 5) (a 3) (c 8) (a 9)))
;-> ((b 5) (c 8))
(map (curry list 'x) (seq 1 5))
;-> ((x 1) (x 2) (x 3) (x 4) (x 5))
See: fn, apply, match, map, filter, clean
syntax: (date)
syntax: (date int-secs [int-offset])
syntax: (date int-secs int-offset str-format)
Description:
Returns a string representation of the current local date
and time. When int-secs is supplied, it is interpreted as
a UTC-based timestamp and converted to local time. An
optional int-offset, in minutes, adjusts the timestamp
before conversion. Invalid int-secs produces nil. When a
custom str-format is given, formatting is performed by
the system strftime implementation. Invalid formats
produce ““.
Format specifiers:
%a abbreviated weekday name
%A full weekday name
%b abbreviated month name
%B full month name
%c locale date and time representation
%d day of month (01–31)
%H hour (00–23)
%I hour (01–12)
%j day of year (001–366)
%m month (01–12)
%M minute (00–59)
%p am/pm indicator
%S second (0–61, leap seconds)
%U week number, Sunday first week
%w weekday number, Sunday = 0
%W week number, Monday first week
%x locale date without time
%X locale time without date
%y year without century (00–99)
%Y year with century
%z time-zone offset/name
%Z time-zone abbreviation
%% literal '%'
Examples:
(date)
;-> "Sat Jan 3 06:46:17 2026"
(date (time))
;-> "Sat Jan 3 06:46:17 2026"
> (date (time) 60)
;-> "Sat Jan 3 07:46:28 2026"
(date (time) 60 "%Y-%m-%d")
"2026-01-03"
> (date 0 0 "%Y-%m-%d")
"1970-01-01"
Notes:
See: time, datelist, datestamp, timelist
syntax: (dateiso)
Description:
Returns current date and time in UTC formatted as YYYY-MM-DD HH:MM:SS.
Examples:
(dateiso)
;-> "2026-01-02 08:51:48"
Notes:
See: date
syntax: (datelist int-seconds [int-index])
syntax: (datelist)
Description:
Converts a UTC timestamp into a list containing year,
month, day of month, hour, minute, second, day of year,
and day of week. The int-seconds is interpreted as the
number of seconds since January 1st, 1970 00:00:00 UTC.
The weekday value ranges from 1 to 7 for Monday through
Sunday. When called without arguments, datelist
uses the current timestamp obtained from time.
If int-index is supplied, only the selected element of
the list is returned. Negative indices count from the end
of the list.
Format of the returned list:
(year month day hour minute second day-of-year day-of-week)
Examples:
(datelist)
;-> (2026 1 3 5 52 59 3 6)
(datelist 0)
;-> (1970 1 1 0 0 0 1 4)
(datelist (time))
;-> (2026 1 3 5 54 9 3 6)
(datelist 1767019672)
;-> (2025 12 29 14 47 52 363 1)
(datelist (time) 0)
;-> 2026
Notes:
int-index returns a single element.syntax: (datestamp str-date str-format)
Description:
Parses a textual date according to strftime-style
directives in str-format and returns the corresponding
UTC timestamp as seconds since January 1st, 1970
00:00:00. The result ranges from 0 up to 2147472000,
which corresponds to dates before the 2038 boundary.
The format directives are the same strftime-style
directives used by date for formatting timestamps.
This allows round-tripping between formatted strings and timestamps when format and locale are consistent.
Examples:
(datestamp "2025.4.3" "%Y.%m.%d")
;-> 1743638400
(datestamp "October 31, 2024" "%B %d, %Y")
;-> 1730332800
(datelist (datestamp "October 31, 2024" "%B %d, %Y"))
;-> (2024 10 31 0 0 0 305 4)
Notes:
nil.syntax: (debug function)
Description:
Enables tracing and evaluates function. This is
shorthand for turning trace on, invoking the
expression, and then restoring the previous trace
state. While trace is enabled, each function call and
return is printed, and errors do not abort execution.
Instead, the function that encounters an exception
returns 0 or nil, allowing program state and
variables to be inspected during debugging.
Examples:
; manual form
(trace true)
(function a b c)
(trace nil)
; equivalent shortcut
(debug (function a b c))
See: trace
syntax: (dec place [num])
Description:
Decrements the numeric value stored in place and returns
the updated result. The operation always uses floating-
point arithmetic. When num is omitted, the decrement is
1.0; otherwise num specifies the amount to subtract.
Integer values are converted to floating point before the
operation. place may be a symbol, a position inside a
list, or any writable location yielding a number.
If place evaluates to nil, it is treated as 0.0 before
the decrement. When place references a writable structure
element, that element is updated in place.
Examples:
(set x 10)
;-> 10
(dec x)
;-> 9
x
;-> 9
(dec x 0.25)
;-> 8.75
x
;-> 8.75
z
;-> nil
(dec z)
;-> -1
(set z nil)
(dec z 0.01)
;-> -0.01
(set l '(1 2 3 4))
;-> (1 2 3 4)
(dec (l 3) 0.1)
;-> 3.9
(dec (first l))
;-> 0
l
;-> (0 2 3 3.9)
(dec (+ 3 4))
;-> 6
Notes:
dec performs floating-point arithmetic.-- for integer-mode decrement.inc for floating-point increment.mac
Description: Creates a named runtime macro. When the macro is called,
its arguments arrive unevaluated. Inside the macro you
decide which arguments to evaluate, when to evaluate them,
and whether to modify them before evaluation. A macro always returns a value. If the macro needs the
result of a computation, it must explicitly call eval.
If eval is not used, the macro returns unevaluated syntax. For anonymous macros, see fn-macro. Examples: Notes: Description: Removes a symbol from the symbol table or deletes all
symbols belonging to a context. After deletion, any
external references to the removed symbol become If Protected symbols, built-in functions, Examples: Deleting an entire context: Notes: Description: Removes the file specified by The file name may refer to a local path or to a URL using
the file:// or http:// schemes. When a URL is used,
additional parameters may be supported; see Examples: Notes: See: urldel, syslasterr,
netlasterr Description: Sends an HTTP DELETE request to the resource specified by
If Examples: Notes: See: fdel, urlget,
netlasterr Description: Sends a termination signal to the process identified by
Process IDs are typically obtained from CAUTION: Examples: Notes: Description: Computes the determinant of a square The optional Examples: Notes: See: mat-invert,
mat-apply,
mat-multiply,
mat-transpose Description: Sets or retrieves the current I/O device. When called
without arguments, the function returns the handle of the
currently active device. When The value A device handle may also be a file descriptor previously
returned by open. When a file descriptor is active, all
high-level I/O functions (print, println, write,
writeln, readc, readln) operate on that file
instead of the console. Any valid open handle can be used as the active I/O
channel. Examples: Notes: See: open, close,
print, readln Description: Computes the difference between two lists. In the first
syntax, the result contains all unique elements that appear
in In the second syntax, difference operates in list mode when
Examples: Notes: Description: Returns a list of directory entry names for the path in
In the pattern form, only filenames matching the regular
expression in Examples: Notes: Description: Checks whether Examples: Notes: See: file? Description: Changes the current working directory to Examples: See: dirpath Description: Successively divides num-1 by each following argument.
Mixed numeric types are allowed, but the result is always
a floating-point number. Any operation involving NaN
propagates NaN. When called with a single argument, div returns the
multiplicative inverse of num-1. Examples: Notes: Description: Evaluates the expressions in Many built-in control structures such as The Examples: Notes: Description: Evaluates the expressions in body first, then evaluates
exp-condition. If exp-condition evaluates to non-nil, the
loop terminates; otherwise the body is executed again.
Because the condition is checked only after the body,
do-until always performs at least one iteration. The return value is the last result produced by body. If
body is empty, the final value of exp-condition is
returned. During iteration, the system iterator symbol
$idx is updated. Examples: Notes: Description: Evaluates the expressions in body first, then evaluates
exp-condition. If exp-condition evaluates to non-nil, the
loop continues; if it evaluates to nil, the loop stops.
Because the condition is checked only after executing the
body, do-while always performs at least one iteration. The return value is the final result of evaluating body.
During iteration, the system iterator symbol $idx is
updated. Examples: Notes: Description: Iterates over unbound arguments passed to the current
user-defined function or macro. The variable in During iteration, the system iterator symbol Examples: Notes: See: args Description: Iterates over each element of If During iteration, the system variable Examples: Notes: Description: Iterates over each character in If The return value is the last evaluation of Examples: Notes: See: dolist, repeat,
char, explode Description: If During iteration, the system variable Examples: Notes: Description: Displays the raw binary fields of a cell. Without an
argument, dump prints information about all allocated
cells to the console. When Each position in the list corresponds to a specific field
in the cell structure: Examples: Notes: See: memcpy Description: Tests whether Examples: Notes: Description: Applies a one-time pad (OTP) transformation to Security depends entirely on the pad: it must be random,
kept secret, and never reused for the same message. When
these conditions are met and the pad length matches the
source length, the result is information-theoretically
secure. The return value is a string containing the encrypted (or
decrypted) data. Examples: Notes: Description: Checks whether str-data ends with str-key. When
num-option is omitted, str-key is treated as a literal
string. When num-option is present, str-key is interpreted
as a regular expression pattern, and num-option selects
the regex options. The function returns true or nil. In the second form, ends-with tests whether a list ends
with the value in exp. exp may itself be a list. Examples: Notes: See: starts-with, regex Description: Accesses and modifies the process environment. In the first form, env returns all environment variables
as an association list of key–value pairs. In the second form, env retrieves the value of the
variable named in var-str, or nil if the variable is not
present. In the third form, env sets or creates an environment
variable. When value-str is an empty string, the variable
is removed from the environment. Examples: Notes: Description: Computes the Gaussian error function of num. The function
is defined as: erf(x) = 2/sqrt(pi) * ∫ from 0 to x of exp(-t^2) dt The return value is a floating-point approximation of the
mathematical erf. Examples: Notes: Description: Installs a custom error handler. When an error occurs,
Rebel resets the current evaluation and invokes the
handler. The handler may be a quoted symbol referring to a
function or an inline fn. Inside the handler,
last-error can be used to inspect the error number and
message. Calling (error-event nil) removes the current handler. Examples: See: last-error, catch, throw-error Description: Evaluates the expression When Examples: Notes: See: mstime Description: Evaluates exp in the current variable environment and
returns the resulting value. Symbols inside exp resolve to
their current bindings at the moment eval is executed.
Evaluation respects local scopes created by let and other
binding forms. Examples: Notes: Description: Compiles and evaluates the code contained in str-source.
If multiple expressions are present, the value of the last
expression is returned. When sym-context is supplied, all
symbols in the string resolve inside that context. If an
error occurs, exp-error is evaluated and its value is
returned. int-offset specifies an optional starting
position inside str-source. Examples: Notes: See: read-expr Description: Checks whether int-number is evenly divisible by 2. If a
floating-point value is supplied, its fractional part is
discarded before testing. Returns true for even integers
and nil otherwise. Examples: See: odd? Description: Starts an external process given in str-process. In the
first form, all lines written to standard output are
returned as a list of strings. When the process cannot be
launched, the result is nil. If it launches but produces
no output, an empty list is returned. In the second form, str-stdin is sent to the process as
standard input. Output from the process is not captured in
this form. The return value is true when the process
starts successfully and nil otherwise. Examples: Description: Applies func-condition to each element of lst in order and
returns the first element for which func-condition yields
true. When no element matches, the result is nil. The
function-condition must be a function or fn that
accepts one argument. Examples: Notes: Description: Terminates the current Rebel process. When int is
supplied, it becomes the process exit code visible to the
host operating system. If no code is given, the exit code
defaults to 0. Examples: Notes: See: throw-error Description: Performs symbolic expansion inside exp. The expansion
rules differ based on the chosen syntax form. In the first syntax, each symbol given in sym-1 … is
replaced with its current value. Nested occurrences are
expanded recursively. The original structure is never
modified. This syntax is useful when building functions
dynamically or when composing rewrite-style macros. In the second syntax, expansion uses list-assoc as a
temporary association list. Keys in list-assoc behave as
symbols and their values supply the replacement data.
When bool is true, the value expressions in list-assoc
are evaluated before substitution. No variable bindings
in the caller are changed. In the third syntax, only symbols beginning with an
uppercase character are expanded. Symbols bound to nil
are skipped. This mode mirrors traditional logic
programming expansion of uppercase variables. Examples: Notes: Description: Splits a string or list into smaller pieces. The meaning of
int-chunk and bool depends on the argument type. In the first syntax, str is split into a list of
single-character strings. If int-chunk is given, str is
split into chunks of that many characters. On UTF-8
systems, chunking respects character boundaries rather
than bytes. When bool is true, the final chunk is omitted
if it is shorter than int-chunk. This form is especially useful when a string operation
needs to work on characters, but the underlying function
operates only on bytes. By exploding into characters first,
processing them, and joining the result afterwards, correct
UTF-8 workflow is preserved. In the second syntax, lst is split into sublists of size
int-chunk. The default chunk size is 1. When bool is true,
the final sublist is omitted if it is shorter than
int-chunk. Examples: Notes: Description: Destructively appends items to a list or string. The first
argument is modified in place, and the updated value is
returned. If list-1 or string-1 is an uninitialized symbol,
it becomes a new list or string during extension. When used on lists, every list-2 is appended to list-1.
When used on strings, every string-2 is concatenated to
string-1. String inputs may contain binary zero bytes. Examples: Notes: Description: Returns a list of the prime factors of int. If int is a
float, it is truncated before factoring. Values smaller
than 2 return nil. For floats larger than the maximum
64-bit integer, the largest 64-bit integer is factored. Examples: Notes: See: apply Description: Appends the content of When operating on local files, The function accepts both file paths and URLs with the
http:// or file:// prefix. When given an HTTP URL,
‘ Examples: Notes: Description: Copies the file located at Examples: Description: Computes the discrete Fourier transform of list-num using
the Fast Fourier Transform algorithm. Each element of
list-num may be either: If list-num has a length that is not a power of two, the
input is padded with complex zeros until the next power of
two is reached. The result is a list of complex numbers in the same
(real imag) structure. fft never modifies the input. Examples: Notes: See: ifft Description: Returns metadata about the file or directory named in
str-name. The result is a list of eight fields. When
int-index is supplied, only that field is returned.
Negative indices work from the end as usual. When bool-flag is nil (or omitted), information describes
the link itself if str-name is a symbolic link. When
bool-flag is true, information describes the file that the
link points to. Fields: Examples: Notes: Description: Checks whether str-path-name exists in the filesystem.
Returns true for both regular files and directories. When bool is true, the path must be a regular file.
If it is a directory, the result is nil. When the path
exists and is a regular file, the function returns
str-path-name. Examples: Notes: See: directory?, file-info Description: Returns a new list containing all elements of exp-list for
which exp-predicate evaluates to true. The predicate is
called once for each element. The original list is not
modified. filter behaves like clean, but with the predicate
logically reversed: filter keeps elements that satisfy the
condition; clean removes them. Examples: Notes: See: clean, index, Description: Searches for exp-key either inside a list or inside a
string. The return value is the zero-based index of the
first match, or nil if no match is found. If the second argument is a list, each element is compared
either with = (default), or using a comparison function in
func-compare. When a regex option is supplied, exp-key must
be a string and the element comparison uses regular
expression rules. If the second argument is a string, find searches for
str-key as a substring or regex pattern. Returned offsets
are byte offsets even on UTF-8 systems. When a match is found, the system variable $0 contains the
matched element or substring. For regular expressions with
capture groups, $1, $2, … contain the submatches. See the
regex function for detailed behavior and
available options. Examples: Notes: See: Description: Collects all matches found in a string or list. The return
value is always a list. If no matches are found, the empty
list () is returned. After each call, the system variable
$count contains the number of matches. In the first syntax, str-regex-pattern is a regular
expression applied to str-text. Each match is collected.
If exp is given, it is evaluated for every match with $0,
$1, … bound to the matched substring and its captures.
regex-option controls regular expression behavior; see
regex. In the second syntax, list-match-pattern is compared
against each element of lst using match. If exp is
supplied, it is evaluated for each match with $it bound to
the current element. In the third syntax, exp-key is compared against elements
of lst using = (default), func-compare, or match when
exp-key is a list. If exp is given, it is evaluated for
each match with $it bound to the element. Examples: Notes: See:
find, regex, match,
unify, search, replace Description: Returns the first element of a list or array, or the first
character of a string. The argument is not modified. When
called on an empty list, an error is raised. On UTF-8 systems, the string form returns the first
character, not the first byte. Examples: Notes: Description: Returns a flattened version of lst. By default, all nested
lists are recursively expanded into a single-level list. When int-level is supplied, only that many levels are
flattened. A level of 0 means no flattening at all. Examples: Notes: Description: Converts exp to a floating-point number. If exp is already a
number or a numeric string, the corresponding float is
returned. If exp cannot be parsed as a float, the result is
nil unless exp-default is supplied, in which case the value
of exp-default is returned. Valid string inputs must begin with a digit, +, −, or .
(period). Strings beginning with other characters cannot be
converted. Extremely large or small exponents produce +inf
or -inf. Examples: Notes: Description: Returns true if exp evaluates to a floating-point number,
otherwise returns nil. Examples: Description: Returns the greatest integer less than or equal to number.
The result is always a floating-point value. Examples: Description: Converts number into a 32-bit IEEE-754 floating value encoded
inside an integer. This is useful when an external C function
expects a 32-bit float rather than Rebel’s native 64-bit float. The returned integer contains the raw 4-byte float bit pattern. Examples: Notes: Description: Constructs an anonymous function. The resulting function
value can be stored in a symbol, passed as an argument, or
returned from another function. For named functions, see
define. When the function is invoked, each formal parameter is
bound to its corresponding argument. Extra arguments are
available through the system symbol $args or through the
function (args). Parameters may specify default values using the form
(sym exp-default). When a call omits such an argument, the
default expression is evaluated and used. The function returns the value of the last body expression. Examples: Notes: Description: Constructs an anonymous runtime macro. When a macro is
called, its arguments arrive unevaluated. Inside the
macro you decide which arguments to evaluate, when to
evaluate them, and whether to modify them before
evaluation. A macro always returns a value. If the macro needs the
result of a computation, it must explicitly call eval.
If eval is not used, the macro returns unevaluated syntax. For named macros, see define-macro. Examples: Notes: See: define-macro, macro, fn Description: Iterates sym over a numeric range from num-from to num-to
(inclusive), evaluating body on each step. When num-step is
omitted, the loop increments by 1. When num-step is present,
sym advances by that floating-point or integer step. A break condition can be supplied in exp-break. When present,
the break expression is evaluated before each iteration, and
if it yields a non-nil value, the loop stops and returns that
value. If exp-break is used, num-step must also be specified. The loop variable sym is dynamically scoped. Its previous
value (if any) is restored after the loop completes or exits. Examples: Notes: See: sequence, repeat,
dolist, dotree Description: Evaluates func-condition on every element of list. If every
evaluation yields a non-nil value, for-all returns true.
If any element fails the condition, the result is nil. This function is the logical “AND” counterpart to exists. Examples: Notes: Description: Creates a new Unix child process. The child begins execution
by evaluating exp, while the parent continues immediately. Both
processes start from the same memory snapshot, but afterwards
they are fully independent. Changes in one do not affect the
other. On success fork returns the child PID; on failure it
returns nil. Examples: Notes: See: wait-pid, destroy,
pipe, spawn Description: Builds a formatted string using str-format and the supplied
data values. The formatting rules follow the ANSI C printf
specification: each format specifier in str-format consumes
one data argument. When using the second syntax, all data
values must be provided inside list-data. format validates the format string and ensures that the
number and type of arguments match the format specifiers.
Use int, float, or string when explicit conversion is
desired. A literal percent sign is written as %% inside
the format string. The general form of a format specifier is: Examples: Format type flags: Extended integer formats: These forms are available for working with full-width integers
used by Rebel. They accept and format 64-bit integers. More examples: Using a list as the data source: Automatic conversion if required by the format: Notes: Description: Computes the frequency of appearance of elements from
list-1 within list-2. The function returns a list of
frequency values aligned with the order of elements in
list-1. list-1 should contain unique items. If list-1 contains
duplicates, only the first occurrence receives a
frequency value, and all following duplicates receive 0. This function is often used to generate frequency tables.
Any type of comparable element may be counted, including
numbers, symbols, and strings. Examples: Description: Extra arguments passed to a function are available
through the system symbol Examples: Notes: Description: Returns the value stored in the default functor of the
given Examples: Notes: Description: Computes the greatest common divisor of one or more
integers. The gcd of two integers that are not both zero
is the largest positive integer dividing both values
without remainder. When more than two integers are given,
the function reduces the sequence from left to right by
repeatedly applying the gcd operation. If only one integer is supplied, that integer is returned.
If all arguments are zero, the result is zero. Negative
arguments are handled by absolute value before reduction. Examples: Notes: See: lcm Description: Reads an 8-bit unsigned value from the memory address in
int-address. This function is used with the FFI when a
foreign function returns a pointer to a byte buffer or to
a structure containing byte fields. The returned value is
an integer in the range 0 to 255. The pointer is taken
as-is. Invalid or stale pointers may terminate the process. Examples: Notes: See: address, get-int,
get-long, get-float,
get-string, pack,
unpack Description: Reads a 64-bit floating-point number in IEEE double
format from the memory address in int-address. This
function is used with the FFI when a foreign function
returns a pointer to a double value or to a structure
containing double fields. The address is taken as-is.
Invalid pointers may terminate the process. Examples: Notes: See: address, get-char,
get-int, get-long,
get-string, pack,
unpack Description: Reads a 32-bit signed integer from the memory address in
int-address. This function is used with the FFI when a
foreign function returns a pointer to a 32-bit integer or
to a structure containing integer fields. The address is
taken as-is. Invalid pointers may terminate the process. Examples: Notes: See: address, get-char,
get-float, get-long,
get-string, pack,
unpack Description: Reads a 64-bit signed integer from the memory address in
int-address. This function is used with the FFI when a
foreign function returns a pointer to a long integer or to
a structure containing 64-bit integer fields. The address
is taken as-is. Invalid pointers may terminate the process. Examples: Notes: See: address, get-char,
get-int, get-float,
get-string, pack,
unpack Description: Copies a sequence of bytes from the memory address in
int-address and returns a Rebel string. When only the
address is given, copying stops at the first zero byte.
This is suitable for reading standard zero-terminated
strings returned by foreign functions. When int-bytes is specified, exactly int-bytes bytes are
copied regardless of zero bytes. When a str-limit string
is supplied, copying stops when this limit sequence is
found or when int-bytes bytes have been read. The address is taken as-is. Invalid pointers may
terminate the process. Examples: Notes: See: get-char, get-int,
get-float, get-long,
pack, unpack Description: Fetches data from the URL in str-url using the HTTP GET
method. Both http:// and file:// URLs are supported. When
no option is given, the function returns the body as a
string. The “header” option returns only the HTTP header. The
“list” option returns a list containing header, body, and
the numeric status code. The “raw” option disables
automatic redirection. The “debug” option prints outgoing
request data. Options may be combined in the same string. The int-timeout value specifies a timeout in milliseconds.
On timeout, get-url returns “ERR: timeout”. Other errors
return a string starting with “ERR:” followed by a
description. The str-header parameter may contain custom HTTP header
lines. Each must end with “\r\n”. When str-header is
supplied, only the GET line, Host:, and Connection:
entries are generated automatically. All other fields come
from str-header. HTTP redirects are followed unless the “raw” option is
used. Chunked Transfer-Encoding responses are unpacked. Rebel does not support HTTPS requests. When HTTPS access
is required, use a proxy configured in the system. Examples: Notes: See: put-url, post-url,
address, get-string Description: Marks one or more symbols as shared. Shared symbols
are accessible without prefix from other contexts.
Only symbols defined in A symbol made shared becomes visible in all other
contexts and can be referenced or called without prefixing
it with Examples: Notes: Description: Checks whether the symbol in Examples: Notes: Description: Returns a list describing the call history of the current
function. Without bool-params, only the names of calling
functions are returned, starting with the current
function. When bool-params evaluates to true, each entry
includes both the function name and the argument pattern
used in the call. Examples: Notes: Description: Evaluates exp-condition. When the condition is neither nil
nor an empty list, exp-1 is evaluated and returned.
Otherwise exp-2 is evaluated and returned. If exp-2 is
omitted, the raw value of the condition is returned. During evaluation, if binds the anaphoric variable $it to
the tested condition value. This allows using $it inside
the true branch. When a branch must execute more than one expression, the
expressions must be grouped using begin. Without begin,
only the first expression would be part of that branch.
Both true and false branches follow this rule. The second form accepts multiple condition–expression
pairs. Evaluation proceeds from left to right and returns
the expression associated with the first true condition.
If the final expression is omitted, the last condition’s
value is returned. This behaves like cond but requires no
parentheses around each pair. Examples: Notes: See: begin, when, unless,
cond Description: Computes the inverse discrete Fourier transform of the
sequence in list-num using an FFT-based method. Each
complex number is represented as a two-element list
(real imag). When a value in the input list is a simple
number, it is treated as a complex value with an
imaginary part of 0.0. If the number of elements in list-num is not an integer
power of two, the sequence is automatically padded with
zeros to the next power of two before transformation. The result is always a list of complex pairs, each pair
containing the real and imaginary components of the
inverse transform. Examples: Notes: See: fft Description: Loads a foreign function from a shared library and makes it
callable from Rebel. The import call returns a callable
function object referencing the foreign symbol. Rebel always uses the extended libffi import API on 64-bit
Unix systems. Argument and return types can be specified
explicitly using type labels. Imported symbols are
protected and can only be rebound using constant. The simple two-argument syntax allows importing foreign
functions without specifying types. This is suitable for
functions returning integers, pointers, or performing
side effects. For fully typed interaction, use the second
syntax with explicit type labels. The third syntax loads a library without importing any
symbol. This is useful when other imported functions
require internal dependencies provided by the library. Strings are passed by address to zero-terminated buffers.
Returned pointers must be freed by the foreign library when
necessary. Rebel only manages memory it allocates itself. Type Rules (LP64 model): On all 64-bit Unix systems Rebel follows LP64: int is
32 bits, long and pointers are 64 bits, and double is
IEEE-754 64-bit. The table shows the valid type labels. Notes on pointer types: General FFI rules: Examples: See: get-string, get-char,
pack, unpack, address Description: Increments the numeric value stored in place using
floating-point arithmetic. When num is omitted, the
value increases by 1.0. When num is supplied, it is
added after converting integers to floating-point
numbers. place may refer to a symbol, a writable element inside
a list structure, or any expression yielding a number.
If place evaluates to nil, it is treated as 0.0 before
the increment. When place designates a writable
location, that location is updated in place. When place
is a computed expression with no writable target, the
incremented result is returned but not stored. Examples: Notes: Description: Applies exp-predicate to every element of exp-list and
returns a list of all indices where the predicate
evaluates to true. Indexing begins at 0. The predicate
may be any test function: a built-in predicate, a
user-defined function, or a fn expression. exp-list is evaluated once before iteration. The order
of indices in the result list matches the order of
elements in exp-list. Examples: Notes: Description: Checks whether float represents a floating-point infinity.
Returns true when the value is +inf or -inf, otherwise
returns nil. The argument is evaluated and must be a
floating-point number; non-float values always yield nil. Floating-point infinities may arise from operations such
as dividing a floating value by zero. Integer division
by zero produces an error instead of an infinite value. Examples: Notes: Description: Converts exp into an integer. When exp evaluates to a
number or a string, its value is parsed and returned as
an integer. If conversion fails, the function returns
nil or, when exp-default is provided, the result of
evaluating exp-default. Strings must begin with one of the following: int-base forces conversion using a specific base. When
int-base is present, prefix rules are ignored and the
string is interpreted strictly in that base. Floating-point values convert by truncation toward zero.
Values exceeding the 64-bit integer range are truncated
to the nearest limit. NaN values convert to 0. Examples: Notes: Description: Checks whether exp evaluates to an integer. Returns true
only when the resulting value is an exact integer. All
other types, including floats, strings, symbols, lists,
and nil, yield nil. Floating-point values that happen to
print without a fractional part are not considered
integers unless explicitly converted. Examples: Notes: Description: Computes the inverse of a square matrix. The matrix may
be given as a nested list or an array. The number of
columns is taken from the length of the first row; if a
row contains fewer elements, missing values are treated
as 0.0. The matrix must be non-singular unless a pivot
override is specified. Inversion is performed using LU-decomposition. When
float-pivot is supplied, it is used to replace pivot
elements that would otherwise become zero during the
decomposition. This allows returning an approximate
inverse even for singular matrices; results depend on
the magnitude of float-pivot. Without float-pivot, singular matrices cause invert to
return nil. Examples: Notes: See: det, mat, multiply, transpose Description: Computes the internal rate of return (IRR) for a cash
flow over time. list-amounts contains outgoing values
(positive numbers) and incoming values (negative
numbers). IRR is the discount rate that makes the net
present value of the entire cash flow equal to 0.0. When list-times is omitted, each entry in list-amounts
is assumed to occur at times 1, 2, 3, … in strictly
increasing order. When list-times is supplied, it must
provide explicit time points for each amount. The computation is iterative. The initial guess defaults
to 0.5 unless num-guess is given. The algorithm stops
when the rate converges to within 0.000001. If no
convergence is reached within 50 iterations, the
function returns nil. Examples: Notes: Description: Retrieves information about the most recent JSON parsing
failure. When json-parse returns nil, this function
returns a two-element list containing an error message
string and the character position at which the parser
detected the problem. If no JSON error has occurred,
json-error returns nil. Examples: Notes: See: json-parse, json-format Description: Concatenates all strings in list-of-strings into a single
string. When str-joint is provided, it is placed between
each element. When bool-trail-joint evaluates to true,
the joint string is also appended after the final
element. All elements of list-of-strings are converted to strings
before concatenation. An empty list produces an empty
string. Examples: Notes: Description: Computes Euclidean distances between the feature vector
in list-data and each row of the given matrix. In the
first form, matrix-centroids contains centroid vectors
from a previous kmeans-train call. In the second form,
matrix-data contains arbitrary data points (nested list
or 2-dimensional array). list-data is an m-element vector. Each row of the
matrix must contain at least m feature values. When row
lengths differ, or when a row contains extra values
(e.g. cluster labels), only the smallest common length
is used. For each row, the Euclidean distance to
list-data is returned. The result is a list of numeric
distances in matrix row order. Examples: Notes: See: kmeans-train,
select,
sort Description: Returns the last element of a list or array, or the last
character of a string. When applied to a list or array,
the final element is returned exactly as stored. When
applied to a string, the result is a one-character
string. An empty list triggers an error. When using a UTF-8
build, last operates on character boundaries, not byte
boundaries. Examples: Notes: Description: Reports information about the most recent runtime error.
If no error has occurred since the session started,
last-error returns nil. When called with no arguments, it returns either nil or
a two-element list containing the last error number and
its full message text. When int-error is supplied, the function returns a list
containing int-error and its associated short error
description. If int-error is outside the known range,
the description defaults to “Unknown error”. Examples: Notes: See: net-error, sys-error,
error-event Description: Checks whether the string str represents a legal Rebel
symbol name. The test does not evaluate str; it inspects
its characters to verify whether the token conforms to
the rules for normal symbol names. Strings that contain spaces, quotes, or other characters
not permitted in standard symbol syntax return nil.
Although such names are not legal tokens, symbols with
those names can still be created explicitly using sym. Examples: Notes: Description: Returns the size of exp according to its type: For all other types, the result is 0. Big integers are counted by their full digit length.
Float digit counts ignore any fractional part. Examples: Notes: Description: Creates local variable bindings for the duration of
body. Each symbol is initialized with the corresponding
expression. In the fully parenthesized form, missing
initializers default to nil. In the flat form, each
symbol must be followed by its initializer. Initializer expressions are evaluated in the environment
that existed before entering the let form. This means
that earlier local bindings created by let do not affect
the evaluation of later initializers. For incremental
initialization (each binding visible to the next), use
letn. The body may contain one or more expressions evaluated
with the local bindings temporarily shadowing any outer
bindings. After body finishes, all local variables are
discarded. Examples: Notes: Description: Performs lexical substitution of symbols in body before
the resulting expression is evaluated. Each symbol in
the initializer list is replaced literally with its
initializer value. This expansion happens prior to
evaluation and produces a rewritten expression which is
then executed. In the fully parenthesized form, initializers are
optional and missing values default to nil. In the flat
form, parentheses around (sym exp) pairs are omitted. letex is useful for generating code where constants or
parameters must be substituted into an expression or a
fn at definition time rather than at runtime. This
is a compile-time–style macro substitution, not dynamic
binding. Examples: Notes: Description: Creates a sequence of nested let bindings, where each
initializer expression sees all bindings created earlier
in the same letn form. This differs from let, where all
initializers are evaluated in the outer scope before any
local bindings are introduced. In the fully parenthesized form, missing initializers
default to nil. In the flat form, parentheses around
(sym exp) pairs may be omitted. The semantics are equivalent to writing several let
forms wrapped inside each other in left-to-right order. Examples: Notes: Description: Evaluates each expression in order and constructs a new
list from the resulting values. Arguments that are
arrays are converted to lists. Nested arrays become
nested lists. Lists created by list are fresh objects
and share no structure with their arguments unless the
arguments themselves were lists. Examples: Notes: Description: Returns true only when exp evaluates to a list. All
other types yield nil. Fn expressions and
fn-macro expressions are also implemented as list
structures and therefore return true under list?. Examples: Notes: Description: Loads and evaluates Rebel source code from one or more
files or URLs. Each file is read, translated into
expressions, and evaluated in sequence. The return value
is the result of the last expression in the last file.
If any file cannot be read or evaluated, load signals an
error. When a sym-context is supplied, all top-level
expressions are evaluated in that context, unless the
file itself contains explicit context switches. If no
context argument is given, evaluation happens in MAIN
unless overridden within the file. File names may be ordinary paths or URLs. The schemes
http:// and file:// are supported. URL and path entries
may be mixed in a single load call. The current context after evaluating load is always the
same as before invoking it. Examples: Notes: Description: Creates local variables initialized to nil, evaluates
body using these bindings, and returns the result of the
last expression. Unlike let or letn, local does not
accept initializer expressions; every listed symbol is
automatically bound to nil. All local bindings shadow any outer bindings for the
duration of body. After evaluation, the original
bindings are restored. Examples: Notes: Description: Computes logarithms of numeric values. In the one-argument
form, log returns the natural logarithm of num. In the
two-argument form, num-base specifies the base of the
logarithm. Both arguments are evaluated before use. The result is a floating-point number. Arguments must be
positive; non-positive values cause a math error. Examples: Notes: See: exp Description: Searches list-assoc for the first association whose key
matches exp-key. An association is a list whose first
element is the key and whose remaining elements are its
values. When a match is found, lookup returns the element
at int-index of that association. If int-index is
omitted, the last element of the association is returned. If no matching key is found, lookup returns exp-default
when provided, otherwise nil. int-index may be negative, in which case elements are
indexed from the end of the association. Examples: Notes: See: assoc Description: Returns a new string with all alphabetic characters in
str converted to lowercase. The original string is not
modified. When running a UTF-8–enabled build, lowercase
conversion operates on full Unicode characters rather
than raw bytes. Examples: Notes: See: upper-case, title-case Description: Creates a named expansion macro. Expansion macros run
during source reading, not at evaluation time. The macro
receives unevaluated syntax and transforms the call
into a new expression. The result of the transformation is
inserted into the code before evaluation. Inside an expansion macro all parameters that should be
replaced in the generated syntax must start with an
upper-case letter. These parameters act as pattern
variables in the expanded expression. Because macro definitions operate at read-time, they cannot
be redefined using define or define-macro. To redefine an
existing macro, use constant. Examples: Notes: See: define-macro, fn-macro Description: Returns true if exp represents a macro. This includes: If exp is a symbol, the symbol’s value is inspected. If the
symbol contains a macro definition, true is returned.
In all other cases nil is returned. Examples: Notes: See: fn-macro, define-macro, macro Description: Creates a directory specified by str-dir-name. When int-mode is given, it specifies the access mode of
the new directory. The function returns true on success
and nil on failure. If no access mode is specified, the system default is
used (typically drwxr-xr-x). The specified access mode is additionally masked by the
process umask. The effective permissions are the result
of: requested mode AND (NOT umask) The current umask can be inspected using the umask
command in the shell. Examples: Notes: See: remove-dir, change-dir Description: Successively applies exp-functor to elements taken from
one or more argument lists and returns the collected
results as a list. exp-functor can be a primitive function, a user-defined
function, or an anonymous function created with fn. The number of arguments passed to exp-functor is
determined by the number of argument lists. Evaluation
stops when the first argument list is exhausted. Extra
elements in other lists are ignored. The return value is always a list, even when arrays are
used as input. Examples: Notes: Description: Performs element-wise arithmetic operations on
two-dimensional matrices. The operation is specified by one of the arithmetic
operators +, -, *, or /. All computations are performed
using floating point arithmetic. In the first syntax, the operation is applied pairwise
to corresponding elements of matrix-A and matrix-B. In the second syntax, each element of matrix-A is
combined with the scalar value number. Matrices are represented as two-dimensional lists or
arrays. Examples: Notes: See: det, invert, multiply, transpose Description: Matches list-pattern against list-match and returns a
list of expressions captured by wildcard symbols in the
pattern. The pattern may contain the wildcard symbols ?, +, and *: Wildcards may be nested. If the pattern cannot be
matched, match returns nil. If the pattern contains no
wildcards, an empty list is returned. When the optional third argument evaluates to true, all
elements involved in the match are returned instead of
only the wildcard captures. Examples: Notes: match is commonly used as a comparison functor in
find, ref, ref-all,
and replace. For logic-style pattern matching, see unify.
For string matching, use regex,
find, or find-all. Description: Evaluates the expressions num-1 and any following numbers
and returns the largest numeric value. All arguments are evaluated before comparison. Integer and
floating-point numbers may be mixed. The return value uses
the numeric type required to represent the maximum value. Examples: See: min Description: In the first syntax, member searches for the element exp
in the list list. If exp is found, a new list is returned
starting with the matched element followed by the rest of
the original list. If exp is not found, nil is returned. When num-option is specified, member performs a regular
expression search instead of a direct comparison. In the second syntax, member searches for the substring
str-key in the string str. If found, the substring of str
starting at the match position is returned. If no match
is found, nil is returned. Examples: Description: Copies The function operates directly on memory addresses and
does not perform any type checks, bounds checks, or
validation. Source and destination are treated as
untyped memory regions. Examples: Notes: See: dump, address,
pack, unpack Description: Evaluates the expressions num-1 and any following numbers
and returns the smallest numeric value. All arguments are evaluated before comparison. Integer and
floating-point numbers may be mixed. The return value uses
the numeric type required to represent the minimum value. Examples: See: max Description: Calculates the modular value of the numbers in num-1 and
num-2. mod computes the remainder from the division of the
numerator num-i by the denominator num-i + 1. The return value is computed as: numerator - n * denominator where n is the quotient of the numerator divided by the
denominator, rounded toward zero to an integer. The result
has the same sign as the numerator and its magnitude is
less than the magnitude of the denominator. When multiple arguments are given, the operation is
applied successively from left to right. In the second syntax, 1 is assumed for num-2 and the
result is the fractional part of num-1. Examples: Use the [%](#f-percent) function when working with
integers only. Description: Returns the time in milliseconds elapsed since the
start of the current day. The value is reset at midnight and increases
monotonically during the day. Examples: Notes: See: etime Description: Evaluates all expressions num-1 and any following numbers,
calculating and returning their product. mul performs mixed-type arithmetic but always returns a
floating-point value. If any argument is NaN, the result
is also NaN. Examples: Description: Returns the matrix multiplication of matrix-A and
matrix-B. If matrix-A has dimensions n by m and matrix-B has
dimensions k by l, the values m and k must be equal.
The result is an n by l matrix. multiply supports mixed-type arithmetic, but the
result always consists of double-precision floating
point values, even if all input elements are integers. The dimensions of a matrix are determined by the
number of rows and the number of elements in the
first row. For missing elements in non-rectangular
matrices, 0.0 is assumed. A matrix may be represented as either a nested list
or an array. Examples: When multiplying a matrix with a vector of n elements,
the vector must first be transformed into an n by 1
matrix using transpose. All operations shown here on lists can also be
performed on arrays. See: det, invert, mat, transpose Description: Tests whether the result of a floating-point arithmetic
operation is a NaN value. NaN stands for “Not a Number” and is a special IEEE 754
floating-point value produced by certain invalid or
undefined numeric operations. All floating-point arithmetic operations involving a
NaN return NaN. All comparisons with NaN return nil.
Integer arithmetic treats NaN as the value 0. Examples: See: inf? Description: Accepts an incoming connection on a socket that was
previously put into listening mode. Returns a newly created socket handle that can be used
to receive and send data on the accepted connection. Examples: Listening on ports below 1024 requires superuser
privileges. See: net-listen, net-close Description: Closes the network socket specified by int-socket.
The socket must have been previously created by
net-connect or net-accept. Returns true on success and nil on failure. When the optional true flag is given, immediate
shutdown is suppressed and the function waits for
any pending data transmissions to finish before
closing the socket. Examples: See: net-connect, net-accept Description: Creates a network socket and prepares it for communication. In the first syntax, connects to remote host specified by
str-remote-host and port specified by int-port. On success,
returns a socket handle. On failure, returns nil. Optional int-timeout-ms specifies connection timeout in
milliseconds. If omitted, a default timeout is used. In the second syntax, str-mode selects UDP-related behavior.
Supported values: When using UDP modes, net-connect does not establish a
stream connection. The socket is prepared for sending and
receiving datagrams. Optional int-ttl specifies multicast
time-to-live value. Default is 3. In the third syntax, connects to a local domain socket
specified by str-file-path. On success, returns a socket
handle. On failure, returns nil. Examples: When using UDP modes, data transfer is performed using
net-send, net-send-to, net-receive, or net-receive-from. See: net-listen, net-accept,
net-send, net-receive Description: Retrieves information about the last error produced by
network-related functions. net-error reports errors from the following functions:
net-accept, net-connect, net-eval, net-listen,
net-lookup, net-receive, net-receive-udp, net-select,
net-send, net-send-udp, and net-service. When one of these functions fails, it returns nil and
net-error can be used to obtain the error number and
message. Each successful call to a net-* function clears the
stored error. Functions that use sockets close the socket automatically
on failure and remove it from the net-sessions list. When called without arguments, net-error returns nil if
no error is stored, or a list containing the last error
number and description. When int-error is specified, net-error returns the error
number and description for that specific error code. Error codes: Examples: See: last-error, sys-error Description: Evaluates source code remotely on one or more Rebel
nodes. net-eval handles connection setup, transmission of
source code, evaluation on the remote node, and
collection of results. The expression exp is evaluated in the environment of
the target node. exp may be: When multiple expressions are provided in a string,
all are evaluated, but only the result of the first
expression is returned. In the first syntax, net-eval sends exp to a single
remote node specified by str-host and int-port. On success, the result of evaluating exp is returned.
On timeout or failure, nil is returned. Optional int-timeout specifies timeout in milliseconds.
Default timeout is 60000 ms. Examples: In the second syntax, net-eval evaluates expressions on
multiple remote nodes. Each element of the list specifies a target node and
expression. The function returns a list of results in
the same order. Nodes that time out return nil. Errors
are returned as (error-number error-text) lists. Examples: When int-port is 0, str-host is interpreted as a local
domain socket path. Optional func-handler specifies a handler function that
is called repeatedly while waiting and once for each
completed remote evaluation. The handler is called with nil while waiting. When a
result is received, it is called with: (str-host int-port result) net-eval returns true if all evaluations complete
before timeout, or nil if the timeout expires. Examples: See: net-connect, net-error Description: Sets or retrieves the default local interface address
used for network connections. When str-ip-addr is specified, it becomes the default
local interface for subsequent network operations.
The address may be given as an IP address or a name. When called without arguments, net-interface returns
the current default interface address. If no interface
has been set yet, the value “0.0.0.0” is returned. This
means the default address selected by the operating
system is used. An explicitly set interface may be overridden by an
optional interface address provided to net-listen. This function is useful on systems with multiple
network interfaces or multiple assigned IP addresses.
On systems with a single interface, network functions
select the interface automatically. On error, the function returns nil. Use net-error to
retrieve error information. Examples: See: net-listen, net-error Description: Sets or retrieves the default Internet Protocol version
used for network operations. int-version must be either 4 for IPv4 or 6 for IPv6.
When called without arguments, net-ipv returns the
current setting. The default protocol version is IPv4. Once a socket is created using net-connect or
net-listen, all subsequent operations on that socket
automatically use the protocol version selected at
creation time. Different sockets may use different
IPv4 or IPv6 settings at the same time. The current protocol setting affects only sockets
created after the change. Note: net-packet operates in IPv4 mode regardless of the
current protocol setting. Examples: See: net-connect, net-listen Description: Creates a listening socket. In the first syntax, binds to int-port and returns a
socket handle immediately. The returned socket is used
with net-accept to wait for an incoming connection. After a connection is accepted, net-accept returns a
new socket handle that is used for communication with
the client. Listening on ports below 1024 requires superuser
privileges. When str-ip-addr is specified, listening is restricted
to that local interface address or name. If omitted,
the default interface is used. Examples: In the second syntax, net-listen creates a local domain
socket specified by str-file-path. On success, returns
a socket handle usable with net-accept. Examples: After a connection is accepted, net-send, net-receive,
net-select, and net-peek can be used as with TCP
connections. UDP mode: When str-mode is “udp” or “u”, net-listen creates a
UDP socket bound to the local address and port. In this
mode, net-accept is not used. The socket can be used directly with net-receive-from,
net-send-to, net-select, or net-peek. Examples: In UDP mode, net-listen binds the socket but does not
establish a connection. UDP multicast mode: When str-mode is “multi” or “m”, net-listen creates a
socket for multicast reception. str-ip-addr specifies
the multicast group address. Examples: Packet divert mode: When str-mode is “divert” or “d”, net-listen creates a
divert socket bound to int-port. str-ip-addr is ignored. This mode requires superuser privileges. The socket
receives raw packets diverted to the specified port
and may re-inject packets back into the kernel. net-receive-from and net-send-to are used for reading
and writing packets on a divert socket. See: net-accept, net-connect,
net-receive, net-receive-from,
net-send-to, net-select Description: Returns local address information for a network
connection associated with int-socket. The return value is a list containing the local IP
address and port number used by the socket. This is useful when the local address or port was
selected automatically by the operating system. On error, the function returns nil. Use net-error
to retrieve error information. Examples: Use net-peer to retrieve the remote address and port
for the same connection. Description: Resolves host names and IP addresses. In the first syntax, net-lookup returns the host name
associated with the IP address given in str-ip-number. In the second syntax, net-lookup returns the IP address
associated with the host name given in str-hostname. When the optional bool argument evaluates to true,
host-by-name lookup is forced even if str-hostname
starts with a numeric IP prefix. On failure, the function returns nil. Use net-error
to retrieve error information. Examples: See: net-error Description: Sends a custom network packet using a raw socket. str-packet must contain a complete IPv4 packet starting
with an IP header, followed by a TCP, UDP, or ICMP header
and optional payload data. The function requires superuser privileges. Only IPv4 is supported. On success, net-packet returns the number of bytes sent.
On failure, it returns nil. Use net-error and sys-error
to retrieve error information. If checksum fields in the packet headers are zero, the
correct checksums are calculated and inserted
automatically. Existing checksums are left unchanged. Examples: Warning: Incorrect use can disrupt network devices. Use only on
isolated networks and only if you understand raw packet
processing. Description: Returns the number of bytes ready for reading on the
network socket specified by int-socket. If no data is available, 0 is returned. If an error
occurs or the connection is closed, nil is returned. This function can be used to implement non-blocking
I/O loops. Examples: Use peek to check file descriptors and standard input. See: net-receive, peek Description: Returns remote address information for a network
connection associated with int-socket. The return value is a list containing the remote IP
address and port number for the connection. On error, the function returns nil. Use net-error
to retrieve error information. Examples: Use net-local to retrieve the local address and port
for the same connection. Description: Sends ICMP echo requests and collects reply information. net-ping uses raw sockets and requires sufficient
privileges to create them. When executed without the
required privileges, the function returns nil and sets
an error retrievable with net-error. In the first syntax, a single address is pinged.
str-address may be a host name, IP address, broadcast
address, wildcard, or range specification. An optional int-timeout specifies the maximum wait
time in milliseconds. If omitted, the default timeout
is 1000 ms. The return value is a list of (ip-address time-us)
pairs for each responding host. If no host responds,
an empty list is returned. A return value of nil indicates an error. Use net-error
to retrieve error information. Examples: In the second syntax, net-ping operates in batch mode.
Multiple addresses are pinged using a single socket.
Addresses may be specified as a list, wildcard (*),
or numeric range (-). Packets are sent as fast as possible. Multiple replies
may be received. Optional int-count limits the number of replies to
collect before returning. A value of 0 or omission
assumes all replies. When bool evaluates to true, an error string is returned
instead of a response time for hosts that do not reply. Examples: Broadcast mode sends a single packet to a broadcast
address and may produce multiple replies. Batch mode
sends one packet per address. Longer timeouts may be required when sending large
address lists. If the timeout expires before all
responses are received, net-ping may return an
incomplete list. See: net-error Description: Receives data from a network socket. Reads up to int-max-bytes from int-socket and stores the
data in sym-buffer. The buffer size is adjusted to the
number of bytes actually received. The return value is the number of bytes read. If the
connection is closed or an error occurs, nil is returned.
Use net-error to retrieve error information. net-receive is a blocking call and waits until data
becomes available. Use net-peek or net-select to check
read readiness. sym-buffer may be a symbol or a default functor used for
reference passing in user-defined functions. When wait-string is specified, net-receive returns as
soon as the given string is received. The wait-string is
included in the contents of sym-buffer. In this mode,
data is read character-by-character and may be slower. Examples: Read until newline: See: net-peek, net-select,
net-error Description: Receives a UDP datagram from int-socket and returns
sender information. The socket must have been created using net-listen or
net-connect with UDP mode enabled. Up to int-max-size bytes are received. Excess bytes are
discarded. On success, the function returns a list containing: (data-string ip-address port) On failure, nil is returned. Use net-error to retrieve
error information. net-receive-from may be used in blocking mode or combined
with net-select or net-peek for non-blocking operation. Examples: In UDP communication, sender address and port are carried
in the packet itself. net-receive does not provide this
information and is therefore not suitable for replying
to UDP senders. See: net-listen, net-connect,
net-send-to, net-select,
net-error Description: Receives a UDP datagram on int-port. Up to int-maxsize bytes are read. Bytes beyond this
limit are discarded. The call blocks until a datagram arrives or until the
optional timeout int-microsec (microseconds) expires. No prior setup using net-listen or net-connect is
required. When setting up a sender/receiver pair, the
receiver must be started first. On success, net-receive-udp returns a list containing: (data-string ip-address port) On timeout or error, nil is returned. Use net-error to
retrieve error information. When str-addr-if is specified, listening is restricted
to the given local interface address or name. When
using str-addr-if, a timeout must also be specified. Examples: net-receive-udp is suitable for short, blocking UDP
transactions. For non-blocking UDP communication or
when replying to multiple senders, use net-listen or
net-connect with UDP mode together with net-receive-from
and net-send-to. See: net-send-udp, net-receive-from,
pack, unpack, net-error Description: Checks readiness of one or more network sockets. str-mode specifies the condition to test: int-micro-seconds specifies the timeout in microseconds.
When set to -1, the call does not time out. In the first syntax, net-select tests a single socket.
It returns true when the socket is ready, or nil on
timeout or error. In the second syntax, net-select tests a list of sockets.
It returns a list of sockets that are ready. If no socket
becomes ready before timeout, an empty list is returned. On error, net-error is set. net-select enables non-blocking read, write, and accept
operations while allowing other parts of the program to
run. Examples: Multiple sockets: Supplying an invalid or closed socket causes an error
to be set in net-error. See: net-accept, net-receive,
net-send, net-error Description: Sends data on a network connection. The contents of str-buffer are sent on the connection
specified by int-socket. When int-num-bytes is specified, at most that many bytes
are sent from the beginning of str-buffer. When omitted,
the entire contents of str-buffer are sent. The return value is the number of bytes actually sent.
On failure, nil is returned. Use net-error to retrieve
error information. Examples: See: net-receive, net-send-to,
net-error Description: Sends data to a specified remote address using an
existing network socket. The socket in int-socket must have been created using
net-connect or net-listen. The function can be used
with both TCP and UDP sockets. When using UDP mode, net-connect or net-listen is used
only to create and bind the socket. No connection is
established. When net-connect is used together with net-send-to,
only one of the two functions should specify the remote
address. The other must pass an empty string as the
address. On success, the number of bytes sent is returned. On
failure, nil is returned. Use net-error to retrieve
error information. Examples: In UDP communication, the sender address and port are
taken from the received packet when replying. For short blocking UDP transactions, use net-send-udp
and net-receive-udp. See: net-receive-from, net-listen,
net-send-udp, net-error Description: Sends a UDP datagram to a remote host and port. No prior setup using net-connect or net-listen is
required. The function sends the datagram and closes
the socket immediately. The return value is the number of bytes sent. On
failure, nil is returned. Use net-error to retrieve
error information. UDP does not guarantee delivery. If no receiver is
waiting, the datagram is lost. For reliable delivery,
a higher-level protocol must be implemented by the
application. The practical maximum payload size is platform-
dependent. Sizes around 8 KB are generally safe. Binary data can be sent using str-buffer. Examples: Broadcast mode: When bool evaluates to true, the socket is put into
broadcast mode and the datagram is sent to all hosts
on the target network. For non-blocking UDP communication or when maintaining
a socket for multiple sends, use net-connect or
net-listen with UDP mode together with net-send-to. See: net-receive-udp,
net-send-to,
net-connect,
net-error Description: Looks up service names and port numbers using the
system services database. In the first syntax, net-service returns the standard
port number associated with str-service for the given
protocol. In the second syntax, net-service returns the service
name associated with int-port for the given protocol. str-protocol is typically “tcp” or “udp”. On failure, the function returns nil. Examples: See: net-error Description: Returns a list of active network sockets currently
managed by the runtime. The list contains both listening sockets and active
connection sockets created by net-listen, net-connect,
or net-accept. This function is useful for inspection, debugging,
and monitoring of open network resources. If no sockets are active, an empty list is returned. Examples: See: net-listen, net-connect,
net-accept, net-close Description: Evaluates exp and returns true only if the result is
strictly nil. For any other value, including the empty
list (), nil? returns nil. This predicate distinguishes between the logical value
nil and all other values that may be considered falsey
in different contexts. Examples: Notes: Note that nil? tests strictly for nil, while true?
matches any value that is neither nil nor the empty
list (). See: true? Description: Generates normally distributed random floating point
numbers using the given mean and standard deviation. In the first form, normal returns a list of length
int-n containing random values with a mean of
float-mean and a standard deviation of float-stdev. In the second form, normal returns a single normally
distributed floating point number. The internal pseudo-random number generator can be
seeded using the seed function. Examples: When no parameters are given, normal assumes a mean of
0.0 and a standard deviation of 1.0. Notes: Description: Evaluates exp and returns true if the result is nil
or the empty list (). For any other value, not
returns nil. not is a logical negation operator and treats both
nil and () as false. Examples: Notes: Description: Returns information about the current date and time
as a list of integers. An optional time-zone offset in minutes can be
specified in int-minutes-offset. This shifts the
time forward or backward before it is split into
individual date-time fields. When int-index is provided, now returns only the
corresponding element from the result list. Examples: The result list contains the following fields: Notes: Daylight savings time types: See: date, date-list,
date-parse, date-value,
time, time-of-day Description: Calculates the number of payment periods required to
repay a loan or investment. num-interest specifies the interest rate per period,
num-pmt is the payment made each period, and num-pv
is the present value. An optional future value can
be given in num-fv. When payments are made at the end of each period,
int-type is 0 or omitted. When payments are made at
the beginning of each period, int-type is 1. Examples: This example calculates the number of monthly payments
required to repay a loan of 100000 at a yearly interest
rate of 7 percent, with monthly payments of 775.30. Notes: Description: Calculates the net present value of an investment
using a fixed interest rate. num-interest specifies the interest rate per period.
list-values contains the cash flow values for each
period. Payments are represented by negative values,
while income is represented by positive values. npv returns the total present value of all cash flows
discounted to the start of the first period. Examples: In the example, an initial investment of 2486.85
allows for an income of 1000 at the end of the first,
second, and third periods. Notes: Description: Returns the element at the position specified by
int-index from a list, array, or string. A single index accesses a single level. Multiple
indices may be used to recursively access elements
in nested lists or arrays. When multiple indices are
used, they must be provided as a list in list-indices.
If more indices are given than nesting levels, the
extra indices are ignored. Negative indices count from the end. Out-of-bounds
indices cause an error. Examples: Multiple indices: Indices may be supplied via a list or vector: Negative indices: Out-of-bounds indices cause an error: Passing lists by reference using a context functor: Passing by reference is faster and uses less memory
for large lists and is recommended for lists with
hundreds of elements or more. Arrays behave the same way as lists: String indexing: In the string form, nth returns the character at
int-index as a string. When UTF-8 support is enabled, nth operates on
character boundaries rather than byte boundaries.
To access single bytes in ASCII or binary buffers,
use slice. Notes: Description: Evaluates exp and returns true if the result is
considered null. The following values are treated
as null: For any other value, null? returns nil. This predicate is useful when filtering or cleaning
results where multiple representations of “no value”
or “invalid value” may occur. Examples: Using null? with filter: Using null? with clean: Notes: Description: Evaluates exp and returns true if the result is a
number. This includes integers, floating point
numbers, and big integers. For any other value,
number? returns nil. Examples: Notes: Description: Checks whether int-number has odd parity. If int-number is not evenly divisible by 2, odd?
returns true; otherwise, it returns nil. When a floating point number is provided, its
fractional part is discarded before the parity
check is performed. Big integers are supported. Examples: Notes: See: even? Description: Opens a file specified by str-path-file using the
access mode given in str-access-mode and returns a
file handle as an integer. The returned handle is
used for subsequent read and write operations. On failure, open returns nil. When the access mode is “write” (or “w”), the file
is created if it does not exist, or truncated to
zero length if it already exists. Access modes: Examples: Reading from the same file: The first example sets the current output device to
the file handle returned by open and writes text
into the file. The second example reads a single
byte at offset 6 from the same file. Calling close on (device) automatically resets the
current device to 0. Options: As an optional third argument, “non-block” or “n”
may be specified together with “read” or “write”.
This enables non-blocking mode, which is useful
when working with named pipes. Notes: See: close, read-char,
seek, print, device Description: Evaluates expressions from left to right and returns
the first result that is neither nil nor the empty
list (). If all expressions evaluate to nil or (), or returns
nil. When called with no arguments, or returns nil. or performs short-circuit evaluation: once a
non-nil, non-empty value is found, remaining
expressions are not evaluated. Examples: Notes: Description: Packs values into a binary string according to a
format specification. When the first argument is a string, str-format
describes the binary layout. The remaining expressions
or the values in list are packed sequentially and
returned as a binary string buffer. The complementary function unpack is used to extract
values from such a binary buffer. pack is typically used when working with binary files,
binary protocols, or foreign function interfaces. When the first argument is a struct symbol, pack uses
the format defined by the struct. In this form, padding
bytes may be inserted automatically to satisfy data
alignment rules defined by the structure layout. If no data expressions or list are provided, the
specified format or structure is filled with zero
bytes. Format specifiers: Floating point values passed to integer formats are
converted to integers. Integer values passed to
floating point formats are converted to floats. Examples: Notes: See: unpack, struct,
address, get-int,
get-long, get-char,
get-string Description: Splits the string produced by evaluating str-data
into a list of string tokens. When str-break is omitted, parse tokenizes the input
according to the language’s internal parsing rules.
This mode uses the same fast tokenizer as source
parsing and is intended for general-purpose token
splitting. When str-break is provided, it specifies how the
input string is split. It may be a literal string
delimiter or a regular expression pattern. If
regex-option is given, str-break is treated as a
regular expression. When no break specification is given, token sizes
are limited by the internal tokenizer. When a break
string or pattern is provided, there is no practical
limit on token length. Examples: Notes: See: regex, find,
find-all, replace,
search, directory Description: Returns the number of bytes ready to be read from
the file descriptor specified by int-handle. If the file descriptor is invalid, peek returns nil.
peek does not read any data; it only reports how many
bytes can be read without blocking. The value 0 may be used to check standard input. Examples: This example checks how many bytes are currently
available on standard input. Notes: For checking sockets or obtaining additional error
information, use net-peek. See: net-peek, read,
read-char Description: Evaluates each argument and returns one of the resulting
values chosen at random. All arguments are treated as
independent expressions, and exactly one of them becomes
the final result. The selection is uniform across the
number of supplied expressions. The random choice is driven by the same internal source
used by rand. To obtain random floating point numbers,
use random, randomize, or normal. To make the selection
sequence repeatable, initialize the generator with seed. Examples: Notes: Description: Creates an inter-process communication pipe and
returns a list containing two file descriptors:
the read end and the write end of the pipe. The returned handles can be passed to a child
process created with process or fork to enable
communication between processes. Examples: In this example, descriptor 3 is used for reading
and descriptor 4 for writing. Notes: Named pipes may also be used. See open for details. See: process, fork,
read, read-line,
open Description: Calculates the periodic payment required to repay
a loan or investment with a constant interest rate
over a fixed number of periods. num-interest specifies the interest rate per period.
num-periods is the total number of payment periods.
num-principal is the present value of the loan.
An optional num-future-value specifies the value
remaining at the end of the periods (typically 0.0). When payments are made at the end of each period,
int-type is 0 or omitted. When payments are made at
the beginning of each period, int-type is 1. The returned value is typically negative, indicating
an outgoing payment. Examples: This example calculates the monthly payment for a
loan of 100000 at a yearly interest rate of 7 percent,
paid over 240 monthly periods. Notes: Description: Removes and returns elements from lists or characters
from strings. In the list forms, pop removes an element from the
list produced by evaluating list. When no index is
specified, the first element is removed. When one or
more indices are given, they are used to locate the
target element, similar to recursive indexing. Indices may also be provided as a list in
list-indexes. This form is convenient when working
with functions such as ref or ref-all, which return
lists of indices. pop modifies the target list in place and returns
the removed element. In the string form, pop removes characters from the
string. With no index, the first character is
removed. With int-index and int-length, a substring
is removed and returned. Examples: Notes: Description: Removes and returns an association from an
association list. In the first form, pop-assoc removes the association
whose key matches exp-key from list-assoc and returns
the removed association. In the second form, list-keys specifies a path of
keys for accessing nested association lists. The
association at the specified path is removed and
returned. pop-assoc modifies list-assoc in place. Examples: Notes: Description: Sends an HTTP POST request to the URL specified by
str-url and returns the response body as a string. POST requests are commonly used to submit form data
or upload content to a server. post-url mimics the
behavior of a web client sending data to an HTTP
endpoint, but it may also be used to send arbitrary
content types, including binary data. When an error occurs, post-url returns a string
starting with the prefix ERR:. An optional timeout may be specified in
int-timeout, given in milliseconds. If no response
is received before the timeout expires, the string
ERR: timeout is returned. When str-content-type is omitted, the default
content type is assumed to be: Examples: Notes: Options: When str-content-type is specified, str-option
accepts the same options as get-url for handling
the returned content. When a timeout is specified,
a custom HTTP header string may also be supplied. Description: Raises num-1 to the power of num-2 and any following
exponents in sequence. When more than two numbers are given, the result of
each exponentiation is used as the base for the next
one. When only num-1 is provided, pow assumes an exponent
of 2. Examples: Notes: Description: Returns the context part of the symbol sym. Examples: Notes: Description: Returns the context part of the symbol sym. Examples: Notes: Description: Controls the formatting of expressions when printing,
saving, or displaying source in an interactive
console. The optional parameters specify formatting settings: When called without arguments, pretty-print returns
the current formatting settings. When parameters are
provided, the settings are updated and the new values
are returned. Examples: The default settings use a maximum line length of 80,
a single space for indentation, and a high-precision
floating point format. Changing the floating point format is useful when
printing values without fractional parts that should
remain distinguishable as floating point numbers. All output operations that rely on automatic
formatting are affected by the current pretty-print
settings. Notes: Examples without formatting: Description: Evaluates exp and returns true if the result is a
primitive symbol. Otherwise, primitive? returns nil. Primitive symbols include all built-in functions
and functions created using import. Examples: Notes: Description: Evaluates each expression and prints the resulting
values to the current I/O device. By default, output
is sent to the console. The current output device may be changed using the
device function. When printing list expressions, elements are
indented according to the nesting level of their
opening parentheses. Strings may contain escape sequences introduced by
the backslash character. Escape sequences: Examples: Notes: Description: Evaluates each expression and prints the resulting
values to the current I/O device. By default, output
is sent to the console. println works like print, but automatically appends
a line-feed character at the end of the output. The current output device may be changed using the
device function. Examples: Notes: See: print, write-line,
device Description: Returns the probability that an observed Chi-square
statistic num-chi2 is equal to or greater than the
given value under the null hypothesis, using
int-df degrees of freedom. prob-chi2 is derived from the incomplete Gamma
function gammai. Examples: Notes: Description: Returns the probability that an observed F statistic
num-f is equal to or greater than the given value
under the null hypothesis. int-df1 and int-df2 specify the numerator and
denominator degrees of freedom. Examples: Notes: See: crit-f Description: Returns the probability that an observed Student’s
t statistic num-t is equal to or greater than the
given value under the null hypothesis, using
int-df degrees of freedom. Examples: Notes: See: crit-t Description: Returns the probability that a normally distributed
random variable with mean 0.0 and standard deviation
1.0 does not exceed the observed value num-z. This corresponds to the cumulative distribution
function (CDF) of the standard normal distribution. Examples: Notes: See: crit-z Description: Starts a new process executing the command specified
by str-command and returns its process identifier. If the process cannot be created, process returns
nil. The new process inherits the execution environment
of the parent process. Command arguments are parsed from str-command using
spaces. Arguments containing spaces must be quoted
explicitly in the command string. The returned process identifier may be used with
destroy to terminate the process if it does not
exit on its own. Standard input, output, and error streams of the
child process may be redirected using pipe handles. Examples: Redirecting standard input and output using pipes: Using an additional pipe for standard error: Waiting for output or error data: If a stream is not required, specify 0 for the
corresponding pipe handle: Notes: See: pipe, peek,
destroy, write,
write-line, read,
read-line Description: Customizes the interactive prompt shown by the
interpreter. The argument may be the symbol of a user-defined
function or an anonymous function. This function
is called each time the prompt is displayed. To restore the default prompt, call prompt-event
with nil. The current context is passed as the single
argument to the prompt handler function. The handler must return a string of at most
63 characters. If no string is returned, the
prompt remains unchanged. Examples: After this call, the prompt shows the current
context, a colon, the current directory, and
a dollar sign. Notes: prompt-event can be combined with command-event
to build customized interactive shells or command
interpreters. See: command-event,
real-path Description: Checks whether the symbol sym is protected. Protected symbols include all built-in functions,
context symbols, and symbols made constant using
the constant function. If sym is protected, protected? returns true;
otherwise, it returns nil. Examples: Notes: See: constant Description: Inserts the value of exp into a list or string. In the list forms, push inserts exp into the list
referenced by list. When no index is given, the
value is inserted at index 0. When one or more
indices are provided, they are used to access a
nested list structure. Indices may also be supplied as a list in
list-indexes. Improper indices are ignored. push modifies the target list in place and returns
a reference to the modified list. If list evaluates to nil, it is initialized to an
empty list before insertion. Repeatedly inserting at index -1 is optimized and
can be used to efficiently append elements. In the string form, push inserts characters into
the string. Indices refer to character positions,
not byte positions. UTF-8 characters are handled
as single characters. Examples: Notes: Description: Sends an HTTP PUT request to the URL specified by
str-url, transferring the content in str-content
to the target resource. HTTP PUT is typically used to upload or replace
the contents of a resource on a server. The server
must be configured to accept PUT requests. If str-url starts with file://, the content is
written to the local file system. On success, put-url returns the response body
returned by the server. On error, it returns a
string starting with ERR:. An optional timeout may be specified in
int-timeout, given in milliseconds. If no response
is received before the timeout expires, the string
ERR: timeout is returned. Examples: Notes: Options: The optional str-option accepts the same options
as get-url for handling returned content. When a
timeout is specified, a custom HTTP header string
may also be supplied. Description: Calculates the present value of a loan or investment
with a constant interest rate and constant payments. num-int specifies the interest rate per period.
num-nper is the total number of payment periods.
num-pmt is the payment made each period. The optional num-fv specifies the future value at
the end of all periods and defaults to 0.0. When payments are made at the end of each period,
int-type is 0 or omitted. When payments are made at
the beginning of each period, int-type is 1. The returned value is typically negative, indicating
an initial outgoing amount. Examples: This example computes the present value of a loan
paid off over 240 periods with constant payments
of 775.30 at a yearly interest rate of 7 percent. Notes: Description: Returns exp without evaluating it. The same effect can be achieved by prepending a
single quote character ‘ to exp. The function quote is resolved at runtime, while
the prefixed ‘ form is translated during code
reading into a quoted expression. Examples: Notes: Description: Generates random integer numbers using the internal
pseudo-random number generator. rand returns a random integer in the range from
0 (zero) to int-range minus 1. When int-range is 0 (zero), the random number
generator is initialized using the current time
value. When the optional int-N parameter is specified,
rand returns a list of int-N random integers. Examples: The first example prints a stream of equally
distributed 0 and 1 values. The second example
returns a list of 100 integers in the range
0 to 2. Notes: Description: Generates evenly distributed floating point random
numbers using the internal pseudo-random number
generator. In the first form, random returns a list of int-n
floating point numbers. Each value is scaled by
float-scale and shifted by float-offset. In the second form, random returns a single floating
point value scaled and shifted in the same way. The sequence produced by random can be made
reproducible by initializing the generator with
seed. Examples: When no parameters are given, random assumes a
default offset of 0.0 and a scale of 1.0. Notes: Description: Rearranges the elements of list into a random order and
returns the resulting list. By default, randomize guarantees that the returned
sequence differs from the previous result produced for
the same list length. To enforce this, the function may
internally generate multiple candidate permutations
until a different ordering is obtained. As a result,
execution time may vary between calls even when the
input list length is identical. When the optional bool argument evaluates to not nil,
the result is allowed to be identical to the input
ordering. This disables the guarantee of producing a
different sequence and avoids the extra work required
to reject equal permutations. randomize operates on lists only and does not modify
the original list. The function relies on an internal pseudo-random number
generator that produces the same sequence of values
each time Rebel is started. Use the seed function to
initialize the generator with a different starting
value. Examples: Notes: Description: Reads up to int-size bytes from the file referenced by
int-file and stores the data into the symbol sym-buffer. Any previous content referenced by sym-buffer is deleted
before reading. After the operation, sym-buffer contains
a string with the data read or nil if no new data was
available. The file handle in int-file must originate from a
previous open call. The file position is advanced by
the number of bytes read. sym-buffer may also be a default functor supplied by a
context symbol, allowing reference-style input and
output in user-defined functions. read is a short form of read-buffer. The longer form
is deprecated and should not be used in new code. When the optional str-wait argument is specified, read
stops early if the given string is encountered in the
input. The wait string is included in the returned
data. The string must not contain binary zero bytes. If str-wait is specified and not found within the
int-size limit, read returns nil. In all cases, any
bytes read are still placed into sym-buffer. Examples: Notes: Description: Reads a single byte from the file referenced by
int-file or from the current I/O device when no
file handle is specified. The file handle in int-file must originate from a
previous open call. Each invocation of read-char
advances the file position by one byte. When the end of the file or device is reached,
read-char returns nil. read-char is intended for byte-wise processing.
For line-oriented input, use read-line together
with device. Examples: Notes: See: write-char, read-line,
device, copy-file Description: Parses the first expression found in str-source and
returns the translated expression without evaluating
it. The optional sym-context argument specifies the context
in which the expression is translated. This controls
symbol resolution during parsing but does not trigger
evaluation. After a successful call, the system variable $count
contains the number of characters consumed from
str-source. If an error occurs while translating the source text,
the expression in exp-error is evaluated and its result
is returned instead. The optional int-offset argument specifies the starting
position inside str-source. This is typically used when
calling read-expr repeatedly, advancing the offset by
the value stored in $count. read-expr behaves like eval-string without executing
the resulting expression. Examples: Notes: See: eval-string, reader-event Description: Reads the entire contents of the file specified by
str-file-name and returns it as a string. On failure, read-file returns nil. When operating on
local files, error details can be retrieved using
sys-error. When used with network resources, additional
information is available through net-error. The function reads the file in one operation and does
not modify the file position of any open handle. read-file also accepts URLs. When str-file-name starts
with http:// or file://, the function behaves like
get-url and supports the same optional parameters. Examples: The file file.txt is read, encrypted using the password
“secret”, and written to a new file named file.enc. The remote file file.tgz is retrieved via HTTP. The
transfer times out after 10 seconds if not completed. Notes: See: write-file, append-file,
get-url Description: Reads a key from the keyboard and returns its numeric
value. For keys representing ASCII characters, the returned
value corresponds to the ASCII code. For navigation
keys and control sequences, multiple read-key calls may
be required to read the complete sequence. When the optional true flag is specified, read-key
operates in non-blocking mode and returns 0 when no key
is available. Without this flag, the call blocks until
a key is pressed. read-key reads from standard input and requires an
interactive terminal. Examples: The loop above can be used to inspect key and control
sequences. To terminate the loop, press Ctrl-A. Notes: Description: Reads a line of text terminated by a line-feed
character (ASCII 10) and returns it as a string. The terminating line-feed is not included in the
returned value. A carriage return (ASCII 13) breaks
the line only when followed by a line-feed, in which
case both characters are discarded. A lone carriage
return breaks the line only if it is the final
character in the input stream. By default, input is read from the current I/O device.
A different device can be selected using device, or a
file handle obtained from open may be supplied in
int-file. There is no intrinsic limit on line length when
reading from files or pipes. When reading from
standard input interactively, line length is limited
and input is optimized for speed. The contents of the most recent read-line operation
are stored internally and can be retrieved using
current-line. When input is exhausted, read-line returns nil. Examples: In the second example, write-line is called without
arguments and outputs the contents of the internal
line buffer filled by the last read-line call. Notes: See: current-line, write-line,
device, open Description: Reads a single UTF-8 encoded character from the file
referenced by int-file and returns its Unicode code
point as an integer. The file handle in int-file must originate from a
previous open call. Each invocation of read-utf8
advances the file position by the number of bytes
used by the UTF-8 character. When the end of the file is reached, read-utf8
returns nil. The returned integer value can be converted to a
displayable UTF-8 character string using char. Examples: The example reads UTF-8 encoded text from a file and
writes it to the terminal. Notes: Description: Installs or removes a reader event handler that is
invoked between the parsing and evaluation stages of
expression processing. When a handler is set, it is called after an expression
has been read and translated, but before it is
evaluated. The handler receives the translated
expression and may return a modified one, which is then
used for evaluation. Specifying nil removes the handler and restores the
default behavior. The handler may be specified as a symbol referring to a
function or as an inline function value. reader-event affects expressions read by load and
eval-string. Examples: The example installs a handler that traces expressions
before evaluation while leaving them unchanged. Notes: See: read-expr, eval-string,
load Description: Returns an absolute path resolved from a relative
filesystem path or from an executable name. In the first form, real-path resolves str-path to its
absolute form. When str-path is omitted, the current
directory “.” is used. In the second form, real-path resolves the full path
of an executable specified by str-exec-name. The
lookup is performed using the search path defined
by the environment. If resolution fails, nil is returned. The returned path length is limited by the maximum
path length supported by the system. Examples: Notes: Description: Receives messages sent from child processes created
with spawn. In the first form, receive reads one message from the
message queue of the child process identified by
int-pid. The received message replaces the contents
of sym-message. Each call reads at most one message. When the message
queue is empty, receive returns nil. Examples: To wait until a message arrives, receive can be used
in a loop: In the second form, receive returns a list of process
IDs for all child processes that currently have
pending messages for the parent process. Examples: The list returned by (receive) contains only process
IDs with unread messages. Calling (receive pid msg)
for these processes is guaranteed to succeed without
blocking. Notes: See: send Description: Searches for the expression exp-key in list and
returns an index vector identifying the position
of the first matching element in a nested list. If no match is found, ref returns nil. By default, ref compares expressions using equality.
When func-compare is supplied, it is used as a
comparison function. The comparison function always
receives two arguments, even if only one is used. When the optional true argument is present, the
matched element itself is returned instead of the
index vector. The index vector returned by ref can be used directly
to index into the original list. Examples: Using comparison functions: Using an anonymous comparison function: Using match and unify as comparison functions: Passing the list by reference using a context: Notes: Description: Works like ref, but returns a list of all index
vectors found for exp-key in list. When no match is found, an empty list is returned. By default, ref-all compares expressions using
equality. When func-compare is supplied, it is used
as a comparison function. The comparison function
always receives two arguments, even if only one is
used. When the optional true argument is present, the
matched elements are returned instead of the index
vectors. After execution, the system variable $count contains
the number of matches found. Examples: Notes: See: ref Description: Performs a Perl Compatible Regular Expression (PCRE)
search on str-text using the pattern in str-pattern. regex returns a list containing the matched string,
followed by the offset and length of the match, and
optionally any captured subexpressions with their
offsets and lengths. If no match is found, nil is
returned. The optional regex-option argument controls matching
behavior. Options can be specified as numbers or as
letters in a string. Multiple options may be combined. The optional int-offset argument specifies the starting
position in str-text where matching begins. After a successful match, the system variables $0,
$1, $2, … contain the full match and captured
subexpressions. These variables are not reset when
no match is found. When no UTF-8 option is specified, offsets and lengths
are reported in bytes. When PCRE_UTF8 is enabled,
offsets and lengths are reported in UTF-8 characters. Examples: Regex options: Notes: See: regex-comp, find,
find-all, replace,
search Description: Pre-compiles a regular expression pattern for reuse
in subsequent regular expression operations. Rebel automatically compiles regular expression
patterns and caches the most recent compilation.
This is sufficient when the same pattern is used
repeatedly. When multiple different patterns are
used in a loop, the cache is not effective. regex-comp allows patterns to be compiled once and
reused efficiently. The compiled pattern is returned
and can be passed to functions that accept regular
expressions. Normal pattern options are specified during
pre-compilation using int-option. When a pre-compiled
pattern is later used, the option value 0x10000 must
be supplied to signal that the pattern is already
compiled. The option 0x10000 may only be combined with 0x8000,
which limits replace to a single substitution. Examples: Notes: See: regex, replace,
ends-with Description: Removes the directory specified by str-path. The directory must be empty for remove-dir to
succeed. If the directory cannot be removed,
nil is returned. Examples: Notes: Description: Renames a file or directory entry from str-path-old
to str-path-new. If the operation succeeds, true is returned.
On failure, rename-file returns nil. Examples: Notes: Description: Executes body int-count times. Before each iteration,
If After Examples: Notes: Description: Performs replacement operations on lists or strings. replace is a destructive function. When operating on
lists, it modifies the list in place and also returns
the modified list. When operating on strings, a new
string is returned. The number of replacements performed is stored in the
system variable $count. During replacement, the anaphoric system variable
$it is bound to the current element or match being
replaced. List replacement: When the second argument is a list, all elements
matching exp-key are replaced with exp-replacement.
If exp-replacement is omitted, all matching elements
are removed from the list. By default, equality is used for comparison. An
optional func-compare argument may specify a
comparison operator or user-defined function. The
comparison function always receives two arguments. String replacement: When the first two arguments are strings, replace
substitutes all occurrences of str-key in str-data
with the evaluated exp-replacement. Regular expression replacement: When a fourth argument is present, str-pattern is
interpreted as a regular expression and regex-option
controls the matching behavior. Replacement proceeds
from left to right. By default, all matches are
replaced. Examples: Notes: See: regex, find,
find-all, parse,
search Description: Resets the execution environment. In the first form, reset returns execution to the
top-level evaluator, disables trace mode, and switches
to the MAIN context. Variable environments are restored
from the saved environments on the stack. reset raises the error condition
“user reset - no error”, which can be intercepted by
user-defined error handlers. It also interrupts
command-line parameter processing and is invoked
automatically after an error condition. During execution, reset walks the entire cell space,
which may take noticeable time in a heavily loaded
system. In the second form, reset terminates the current
process and starts a new clean process using the same
command-line parameters. In the third form, reset changes the maximum number of
cells available to the runtime system. The new limit
is reported by sys-info. Cell memory does not include
string storage referenced by cells. The minimum allowed cell count is 4095. Values below
this threshold are clamped to 4095. The program exits
when attempting to allocate more cells than permitted. Examples: Notes: See: sys-info Description: Returns all elements of a list or array except the
first one. When applied to a string, rest returns a new string
containing all characters except the first character. For empty lists, rest returns an empty list. rest operates on character boundaries when UTF-8
support is enabled. Examples: Notes: Description: Reverses the order of elements in a list or array,
or the order of characters in a string. When applied to a list or array, reverse is
destructive: it modifies the original object and
also returns it. When applied to a string, reverse returns a new
string with characters in reverse order. For UTF-8 strings, reversing operates on character
boundaries when combined with explode. Examples: Notes: See: sort Description: Rotates the elements of a list or the bytes of a
string and returns the result. rotate is destructive: it modifies the original
list or string and also returns it. When int-count is positive, rotation is performed
to the right. When int-count is negative, rotation
is performed to the left. If int-count is omitted,
a rotation of one position to the right is applied. Examples: Notes: Description: Rounds number to the precision specified by
int-digits. When int-digits is positive, rounding is applied
to the integer part of the number. When int-digits
is negative, rounding is applied to decimal places. If int-digits is omitted, rounding is performed
to zero decimal digits. Examples: Notes: See: format Description: Writes symbols and contexts to a file in textual
form. In the first form, save writes the entire workspace
to str-file. Loading this file later restores the
workspace to the same state as when save was invoked. System symbols, built-in function symbols, symbols
starting with the $ character, and symbols containing
nil are not saved automatically. In the second form, one or more symbols may be
specified. When a symbol is given, only that symbol
is saved. When a context symbol is given, all symbols
contained in that context are saved. Symbols and
contexts may be mixed. System symbols are saved only when specified
explicitly. Symbols are serialized using set statements, or
using define / define-macro when the symbol contains
a function or macro definition. save always serializes symbols as if the current
context were MAIN, ensuring consistent output
regardless of the active context. On successful completion, save returns true. Examples: Notes: Description: Searches a file referenced by int-file for the
string or pattern specified in str-search. The file handle in int-file must originate from a
previous open call. After the search, the file
position is updated as follows: When regex-option is not specified, a fast plain
string search is performed. When regex-option is specified, str-search is treated
as a regular expression and matching follows PCRE
rules. In this case, captured subexpressions are
stored in the system variables $0 to $15. On success, search returns the new file position.
On failure, nil is returned. Examples: Notes: See: regex, find,
find-all, parse,
replace Description: Initializes the internal random number generator used by
amb, normal, rand, random, and randomize. When called with a single argument, seed initializes the
generator using the standard C library random source.
All subsequent calls to random-related functions follow
the sequence defined by this generator. When the second argument evaluates to true, seed switches
to an internal deterministic generator that is independent
of the C library implementation. This generator produces
reproducible sequences across builds and executions when
initialized with the same seed value. The optional int-pre-N parameter specifies how many random
values are generated internally during initialization.
This advances the generator state before it is used.
When omitted, int-pre-N defaults to 50. Only the lower 32 bits of int-seed are used to initialize
the generator. When called without arguments, seed returns the current
internal seed state as an integer. This value can later be
used to restore the generator to the same state. Examples: Notes: See: random, rand,
normal, pick Description: Accesses the target object of a FOOP method call.
The object referenced by self is automatically set
by the : colon operator when invoking a method. When called without indices, self refers to the
entire object. One or more int-index arguments may
be used to access individual object members. Objects accessed through self are mutable. Any
modification performed on self or its indexed
members directly affects the original object. self is only valid inside a FOOP method. Outside
of a method call, self is not defined. Examples: Notes: Description: Sets the file position for the open file identified
by int-file. When int-position is specified, the file pointer is
moved to that absolute position counted from the
beginning of the file. A value of 0 refers to the
start of the file. When called without int-position, seek returns the
current file position. When int-position is -1, the file pointer is moved
to the end of the file. If int-file is 0, seek returns the number of bytes
written to standard output. On failure, seek returns nil. seek may position the file pointer beyond the
current end of the file. Writing at that position
extends the file and fills the gap with zeros.
Such files are sparse files; unused blocks are
not physically allocated on disk. Examples: Notes: Description: Selects one or more elements from a list or one or
more characters from a string using index values. When operating on a list, select returns a new list
containing the elements located at the indices
specified in list-selection or by the individual
int-index_i arguments. When operating on a string, select returns a new
string composed of the characters located at the
specified indices. Indices may be positive or negative. Negative
indices count from the end, where -1 refers to the
last element or character. Selected elements may be repeated and do not need
to appear in ascending order. Reordering indices
reorders the result accordingly. Examples: Notes: Description: Creates and controls a system semaphore used for
interprocess synchronization. A semaphore maintains a counter value between zero
and a system-defined maximum. A value greater than
zero represents the signaled state. A value of zero
represents the non-signaled (blocking) state. Calling semaphore without arguments creates a new
semaphore and returns its integer identifier. The
initial semaphore value is zero. Calling semaphore with int-id only returns the
current value of the semaphore. Calling semaphore with int-id and a positive or
negative integer attempts to adjust the semaphore
value by that amount: The semaphore value is never allowed to become
negative. Blocking occurs automatically when this
would happen. Calling semaphore with int-id and a final argument
of 0 releases the semaphore and frees all associated
system resources. Any blocked processes waiting on
this semaphore are released. On failure, semaphore returns nil. Use sys-error
to retrieve the underlying system error. Examples: Example with a child process: Notes: Description: Sends a message between a parent process and its
child processes created with spawn. send implements asynchronous message passing using
paired send and receive queues. No locks, semaphores,
or shared memory are required. Each process owns its own receive queue. send places
a message into the target process receive queue. Only processes started with spawn can use send and
receive. Processes created with fork or process
must use other IPC mechanisms. When called with int-pid and exp, send attempts to
enqueue exp into the receive queue of the target
process identified by int-pid. The target may be
either the parent process or one of its spawned
child processes. When called without arguments, send returns a list
of child process IDs whose receive queues can
currently accept messages. This form is used only
by the parent process. If the target receive queue is full, send returns
nil. The message is not queued. Messages may contain any valid expression: numbers,
strings, symbols, or list expressions. Message size
is not limited. Examples: Notes: See: receive, spawn,
sync, eval Description: Generates a numeric sequence starting at num-start
and ending at num-end. When num-step is omitted, a step size of 1 is used
and the generated values are integers. When num-step is specified, it must be a positive
number. In this case, the generated values are
floating-point numbers. The sequence direction is determined automatically.
If num-start is greater than num-end, the sequence
counts downward. If num-start is less than num-end,
the sequence counts upward. The end value num-end is included if it lies exactly
on the generated sequence. Examples: Notes: Use series to generate geometric
sequences. Description: Generates a sequence of values derived from a
starting value. In the first syntax, series generates a geometric
sequence of num-count elements starting at
num-start. Each subsequent element is multiplied
by num-factor. The generated values are always
floating-point numbers. If num-count is less than 1, an empty list is
returned. In the second syntax, series generates a sequence
by repeatedly applying function to the previous value.
The first element is exp-start, and each following
element is the result of calling function with the
previous element. The internal index variable $idx is updated for
each generated element and can be referenced
inside function. Examples: Notes: Use sequence to generate arithmetic
sequences. Description: Evaluates both arguments and assigns the result of
each exp to the symbol specified by sym. The assignment is performed by copying the contents
of the right-hand side into the symbol. The previous
contents of the symbol are discarded. The set expression returns the result of the last
assignment performed. An error is raised when attempting to modify the
symbols nil, true, or a context symbol. set accepts multiple symbol/expression pairs and
processes them from left to right. Examples: Notes: Description: Reports or changes the process locale. When called without arguments, set-locale returns
the currently active locale and the decimal point
character as a list. When str-locale is specified, the locale is changed.
An empty string selects the default locale of the
current system. When int-category is omitted, all
locale categories are affected (LC_ALL). When int-category is specified, only that category
is changed. Category values correspond to those
defined by the system C library. On success, set-locale returns a list containing
the active locale string and the decimal separator.
On failure, it returns nil. Examples: Locale categories: Notes: Description: Searches for exp-key in list and replaces the first
matching element with exp-replacement. The search descends recursively into nested lists.
When a match is found, the element is replaced and
the modified list is returned. During replacement, the system variable $it is
bound to the matched expression and may be used
inside exp-replacement. If function-compare is specified, it is used to compare
exp-key with list elements. Without function-compare,
default equality comparison is used. The original list is modified when passed by
reference. Examples: Notes: See: set-ref-all, replace,
ref Description: Searches for exp-key in list and replaces all
matching elements with exp-replacement. The search descends recursively into nested lists.
Each matching element is replaced and the modified
list is returned. During replacement, the system variable $it is
bound to the currently matched expression and may
be used inside exp-replacement. After completion, the system variable $count
contains the number of replacements performed. If function-compare is specified, it is used to compare
exp-key with list elements. Without function-compare,
default equality comparison is used. The original list is modified when passed by
reference. Examples: Notes: See: set-ref, replace,
ref-all, match Description: setq and setf assign values to places. Both forms are implemented by the same built-in
function and behave identically. The distinction
is conventional and used throughout this manual: Assignments overwrite the previous contents of the
target place. Multiple place/expression pairs may
be specified and are evaluated from left to right.
The return value is the result of the last
assignment. Examples: Notes: Description: Evaluates the sign of num. In the first syntax, sgn returns an integer value
according to the sign of num: In the second syntax, sgn returns the result of
evaluating one of the optional expressions instead
of the numeric sign values. The expressions correspond to the following cases: If the expression corresponding to the triggered
case is omitted, sgn returns nil. Examples: Notes: Description: Provides access to shared memory for communication
between parent and child processes. When called without arguments, share requests a
shared memory region from the operating system and
returns an integer address that can be stored for
later use. When called with int-address and exp-value, the
value of exp-value is written into the shared memory
region. The value written is also returned. When called with int-address only, share returns
the value currently stored in the shared memory.
If no value has been written yet, nil is returned. When called with nil and int-address, the shared
memory region is unmapped and released. Using a
shared address after unmapping results in undefined
behavior. Shared memory can be accessed only between a parent
process and its child processes. Examples: Notes: Description: Installs, modifies, or queries a signal handler for
the signal specified by int-signal. When a symbol or function expression is supplied,
it becomes the user-defined handler for the signal.
The handler argument is not evaluated at setup time. When one of the string options is supplied, the
signal handler is set as follows: The option strings are case-insensitive and may be
abbreviated to their first letter. When called with only int-signal, signal returns
the currently installed handler symbol or nil if
no handler is defined. Examples: Handler as inline function: Query current handler: Setting multiple signals to one handler: Notes: Description: Evaluates one or more expressions while suppressing
console output of the return value and the prompt. silent behaves like begin, but discards any output
that would normally be printed after evaluation.
It is typically used when the return value is not
needed, such as when Rebel is controlled by another
application. Silent mode is automatically reset when execution
returns to the prompt. When called without arguments, silent enables silent
mode for the next expression. Examples: Notes: Description: Calculates the sine of num-radians and returns the
result as a floating-point number. The argument is interpreted as an angle measured
in radians. Examples: Notes: Description: Calculates the hyperbolic sine of num-radians and
returns the result as a floating-point number. The hyperbolic sine is defined as: (exp x - exp (-x)) / 2 Large values of num-radians may cause the result to
overflow to inf. Examples: Notes: Description: Extracts a portion of a list, array, or string and
returns it as a new value. The original object is
left unchanged. For lists and arrays, slice copies elements starting
at int-index. When int-length is specified, that
number of elements is copied. If int-length is negative, it is treated as an
offset counted from the end, and elements are copied
up to (but not including) that offset. If int-length is omitted, all elements from
int-index to the end are copied. For strings, slice extracts a substring starting at
int-index with length int-length. When int-length
is omitted, everything to the end of the string is
copied. slice operates on byte boundaries, not character
boundaries. Examples: Notes: See: explode, join,
select, nth Description: Extracts a portion of a list, array, or string and
returns it as a new value. The original object is
left unchanged. For lists and arrays, slice copies elements starting
at int-index. When int-length is specified, that
number of elements is copied. If int-length is negative, it is treated as an
offset counted from the end, and elements are copied
up to (but not including) that offset. If int-length is omitted, all elements from
int-index to the end are copied. For strings, slice extracts a substring starting at
int-index with length int-length. When int-length
is omitted, everything to the end of the string is
copied. slice operates on byte boundaries, not character
boundaries. Examples: Notes: See: explode, join,
select, nth Description: Sorts the elements of list or array in ascending
order and returns the sorted object. The operation is destructive: the original list or
array is reordered in place. Elements of any type may be sorted. When elements
are themselves lists or arrays, comparison is
performed recursively. When values of different
types are compared, ordering follows this hierarchy: Atoms:
nil, true, integer/float, string, symbol, primitive Lists:
quoted expression, list, fn, macro The sorting algorithm is a stable binary merge sort
with approximately O(n log2 n) performance. Adjacent
elements that compare equal preserve their order. An optional comparison operator or function may be
supplied. When provided, it must be compatible with
<= or >= semantics to preserve stability. Examples: Notes: Description: Serializes symbols, definitions, and contexts into
a string representation. source behaves like save, but writes the serialized
output to a string instead of a file. When called without arguments, source serializes
the entire workspace. When one or more symbols are specified, only those
symbols are serialized. Context symbols cause all
symbols contained in that context to be serialized
as well. Symbols with a value of nil are not serialized.
System symbols beginning with the $ character are
serialized only when explicitly specified. Symbols not belonging to the current context are
written with their context prefix. Examples: Notes: See: save, pretty-print,
context Description: Starts the evaluation of exp in a new child process
and returns immediately. The symbol sym is quoted and will receive the result
of the evaluation when sync is executed. spawn is
used to evaluate expressions concurrently in
separate processes. spawn always creates a new process. It does not
limit the number of spawned processes and does not
take the number of CPU cores into account. Actual parallel execution is determined entirely by
the operating system scheduler. When the optional third argument evaluates to true,
the spawned process is enabled for communication
using send and receive. After successfully starting a child process, spawn
returns the process ID of the child. Examples: Notes: See: sync, abort,
send, receive,
fork Description: Calculates the square root of num and returns the
result as a floating-point number. Examples: Notes: Description: Calculates the sum of squares of the numeric elements
in list-vector or array-vector and returns the result. Examples: Notes: Description: Checks whether a string or list begins with a given
value. In the first form, starts-with tests whether the
string str begins with the key string str-key. The
function returns true on success or nil otherwise. When num-option is specified, str-key is treated as
a regular expression pattern. The value of
num-option controls regular expression options. In the second form, starts-with tests whether list
begins with the element exp. The comparison is done
on the first element of the list. Examples: Notes: Description: Calculates statistical values describing central
tendency and distribution moments of the numeric
values in list-vector. The function returns a list containing the following
values in this order: N
Number of values mean
Mean of values avdev
Average deviation from the mean sdev
Standard deviation (population estimate) var
Variance (population estimate) skew
Skewness of the distribution kurt
Kurtosis of the distribution Examples: Output: Notes: Description: Converts the result of evaluating one or more
expressions into a string. When multiple expressions are specified, each
expression is converted to a string and the results
are concatenated in order. Examples: Zero bytes: If a buffer passed to string contains zero bytes
(\000), copying stops at the first terminating
zero. Notes: Description: Evaluates exp and tests whether the result is a
string. Returns true if the evaluated expression is a
string, otherwise nil. Examples: Description: Defines an aggregate data type for use with foreign
functions imported via libffi. struct is used together with import, pack, and
unpack to describe C-compatible structure layouts.
This enables calling C functions that accept struct
values or pointers to structs. The symbol names the structure type. Each
str-data-type specifies one field in declaration
order and must match the corresponding C type and
platform ABI. struct returns the symbol naming the defined
structure. Examples: Notes: See: import, pack,
unpack, address Description: Subtracts the values in num-2 and following arguments
successively from num-1. The function performs mixed-type arithmetic and accepts
integers and floating point numbers as arguments. The
result is always returned as a floating point number,
even when all arguments are integers. When called with only one argument, sub returns the
negated value of num-1. If any argument involved in the calculation is NaN,
the result is NaN. Examples: Description: Swaps the contents of place-1 and place-2. A place can refer to the contents of an unquoted
symbol or to an addressable location inside a list
or array. Valid places include references created
with first, last, nth, implicit indexing, and places
returned by assoc or lookup. swap is a destructive operation. It modifies the
lists, arrays, or symbols involved directly and does
not create copies of the exchanged values. Any two places may be swapped, whether they belong
to the same object or to different objects. Examples: Notes: See: set, setf, first,
last, nth, assoc,
lookup Description: Translates the first argument into a symbol and returns
it. The first argument may be a string, number, or
symbol. If sym-context is omitted, the current context is used
for symbol lookup or creation. When sym-context is
specified, lookup and creation take place in that
context. If the context does not exist and sym-context
is given as a quoted symbol, the context is created.
If sym-context is unquoted, it is interpreted as an
existing context or a variable containing a context. By default, symbols are created when they do not already
exist. When the optional third argument nil-flag
evaluates to nil, symbol creation is suppressed. In
that case, sym returns nil if the symbol is not found.
This form can be used to test for the existence of a
symbol. sym can create symbols that are not legal identifiers
in source code, such as numeric names or names
containing special characters. This makes sym suitable
for associative memory access similar to hash tables
in other languages. When the first argument is a symbol, its name is
extracted and used as the symbol name in the target
context. Examples: Notes: See: context, set, setf,
delete, symbols Description: Evaluates the expression exp and returns true if the
resulting value is a symbol. Otherwise, nil is returned. symbol? tests the value produced by evaluation, not
the syntactic form of the expression. Examples: Notes: Description: Returns a sorted list of all symbols defined in a
context. When called without arguments, symbols returns the
symbols defined in the current context. When a context
is specified, symbols defined in that context are
returned. The context may be given as a quoted symbol, an
unquoted context name, or a variable containing a
context. Contexts evaluate to themselves, so quoting
is optional. Examples: Notes: Description: Synchronizes child processes launched with spawn. When called with int-timeout specified in milliseconds,
sync waits for spawned child processes to finish. As
each child process completes, the evaluation result of
the spawned subtask is assigned to the symbol specified
in the corresponding spawn statement. The function returns true when all child processes have
been processed. If the timeout is reached while child
processes are still pending, sync returns nil. If an optional inlet function func-inlet is provided,
it is called with the child process identifier (PID)
as its argument whenever a child process finishes.
func-inlet may be a function symbol or an anonymous
function. When called without arguments, sync returns a list of
PIDs for child processes whose results have not yet
been processed. Examples: Notes: sync is part of the Cilk API for process
synchronization and parallel execution. Description: Reports the last error generated by the underlying
operating system. When called without arguments, sys-error returns a
list containing the system error number and the
corresponding error message text. If no system error
has occurred, nil is returned. When int-error is greater than zero, sys-error returns
the error number and its associated error text without
changing the current error state. Specifying 0 as int-error resets the stored system
error. After resetting, a subsequent call to
sys-error returns nil. System errors are typically set when functions that
access system resources return nil. Common causes
include nonexistent files, insufficient permissions,
or exhaustion of system resources such as file
descriptors. The exact error numbers and messages depend on the
platform C library. Examples: Notes: See: last-error, net-error Description: Returns internal runtime and system information. When called without arguments, sys-info returns a list
of integers describing internal resource usage and
runtime state. When int-idx is specified, only the element at that
index is returned. Negative indices may be used to
access elements from the end of the list. The returned list contains the following entries: The operating system value uses the following base
constants: Additional feature flags may be ORed into this value: To preserve compatibility with future extensions, it
is recommended to access fixed fields using offsets
0 through 5, and to use negative offsets for entries
near the end of the list. Examples: Notes: See: sys-error, last-error Description: Performs Student’s t-tests for comparing mean values. In the first syntax, t-test performs a one-sample
Student’s t-test comparing the mean of list-vector
against number-value. The result is returned as a list with the following
elements: Examples: In the second syntax, t-test compares the means of
two data vectors using a two-sample Student’s t-test. When the optional true flag is omitted or nil, the
samples are treated as independent and may differ
in length. When the flag is true, a paired t-test is performed,
assuming both vectors contain measurements from the
same subjects taken under different conditions. The returned result list contains: Examples: In the third syntax, Welch’s t-test is used when the
variances of the two samples differ significantly. When float-probability is specified, t-test first
performs an F-test on the variances. If the probability
of the F-ratio is below float-probability, Welch’s
t-test is applied. Specifying 1.0 forces the Welch
method unconditionally. Examples: Notes: Description: Calculates the tangent of the angle specified by
num-radians and returns the result. The argument is interpreted as an angle in radians.
The result is returned as a floating point number. Examples: Notes: Description: Calculates the hyperbolic tangent of num-radians. The hyperbolic tangent is defined as the ratio of
the hyperbolic sine to the hyperbolic cosine: tanh(x) = sinh(x) / cosh(x) The argument is interpreted as a real number. The
result is returned as a floating point value. Examples: Notes: Description: Returns the term part of symbol as a string, without
the context prefix. The term is the symbol name following the context
separator. The returned value is always a string. Examples: Notes: Description: Transfers control to the nearest enclosing catch
expression and supplies exp as the result value. throw works together with catch. When throw is
executed, evaluation stops at that point and the
corresponding catch returns immediately. The value of exp is assigned to the result symbol
specified in the catch call, or returned directly
when catch is used without a result symbol. throw does not signal an error condition. It is a
controlled, non-error flow transfer mechanism. Examples: Notes: See: catch, throw-error Description: Signals a user-defined error exception with the
message produced by evaluating exp. throw-error aborts normal evaluation and raises an
error condition. The error message is reported as a
user error and can be handled like any other runtime
error using error handlers, error-event, or the
catch form that captures error exceptions. Unlike throw, throw-error represents an actual error
state and is intended for invalid arguments or
illegal conditions detected by user code. Examples: Notes: See: throw, catch,
error-event, last-error Description: Converts a given UTC date and time into the number of
seconds since January 1st, 1970 00:00:00. The first form
accepts separate numeric fields for year, month, and day,
with hour, minute, and second optional. The second form accepts a list containing the same fields in
the same order. Missing time fields default to zero. In the third form, The conversion always uses UTC and does not apply the
local time zone. Examples: See: date,
datelist,
datestamp,
timelist Description: Returns a copy of the string in str with its first
character converted to uppercase. When the optional bool argument evaluates to a
non-nil value, the remainder of the string is
converted to lowercase. When bool is nil or omitted,
only the first character is affected. The original string is not modified. Examples: Notes: See: lower-case,
upper-case Description: Controls tracing and interactive debugging of
expression evaluation. When called with int-device, trace writes a continuous
log of all expression entries and exits to the given
device. The device is typically a file descriptor
returned by open. When int-device is 1, output is
written to standard output. When called with a value evaluating to true, trace
enables interactive debugger mode. In this mode,
execution stops at each expression entry and exit
and waits for user input. Expressions are highlighted by enclosing them in
the trace highlight character (default ‘#’). This
character can be changed using trace-highlight. When called with nil, trace disables tracing and
debugger mode and closes any open trace output. When called without arguments, trace returns the
current tracing or debugging mode. Examples: Notes: See: debug, trace-highlight Description: Configures how expressions are highlighted during
trace and interactive debugging. The strings str-pre and str-post define the markers
used to enclose the currently active expression.
By default, the number sign ‘#’ is used. The marker
strings may be up to seven characters long. When the terminal supports control sequences, the
highlight strings may contain terminal control codes
to change color, intensity, or other attributes. Optional str-header and str-footer strings control
the separator and debugger prompt. The header may be
up to 15 characters long and the footer up to 31
characters long. Examples: Notes: Description: Transposes a matrix by reversing its rows and columns. The argument matrix may be a nested list or an array.
The matrix may contain values of any data type. Matrix dimensions are determined by the number of rows
and by the number of elements in the first row. During
transposition, matrices are made rectangular by
assuming nil for missing elements, ignoring superfluous
elements, or expanding non-list rows into repeated
elements. Examples: Notes: See: det, invert,
mat, multiply Description: Removes leading and trailing characters from the
string str and returns a new string. With the first syntax, all leading and trailing
whitespace characters are removed. With the second syntax, characters specified in
str-char are stripped from both sides. When
str-char is an empty string, the space character
is assumed. With the third syntax, different characters may be
trimmed from the left and right sides. Specifying
an empty string for one side disables trimming on
that side. Examples: Notes: See: replace,
lower-case,
upper-case Description: Evaluates the expression exp and returns true if the
result is neither nil nor the empty list (). Otherwise,
nil is returned. true? uses the same truth semantics as if. Both nil
and the empty list () are considered false. Examples: Notes: Description: Evaluates and attempts to unify exp-1 and exp-2. Two expressions unify if they are equal, or if one of
them is an unbound variable which can be consistently
bound to the other expression. When both expressions
are lists, unification proceeds recursively by
comparing corresponding subexpressions. Unbound variables are symbols starting with an
uppercase character. On success, unify returns an
association list of variable bindings. When no
variables are bound but the match succeeds, an empty
list is returned. When unification fails, nil is
returned. The underscore symbol ‘_’ matches any atom, list, or
unbound variable and never binds. An optional association list list-env may be supplied
to pre-bind variables. This is useful when chaining
multiple unification steps. unify implements a unification algorithm with a
correctly applied occurs check, preventing infinite
or circular bindings. Examples: Notes: Use unify with expand to substitute bound variables: Use unify with bind to destructure data: See: match, expand,
bind, find,
ref, replace Description: Returns a list containing the unique elements found
in two or more lists. Elements are collected from the input lists in order
of appearance. Each element appears only once in the
result, even if it occurs multiple times in the input
lists. Examples: Notes: See: difference, intersect,
unique Description: Returns a list containing the elements of list with
all duplicate entries removed. The order of elements is preserved based on their
first occurrence in the input list. Examples: Notes: See: difference, intersect,
union Description: Evaluates the expressions in body only when
exp-condition evaluates to nil or the empty list (). If body is executed, the result of its last
expression is returned. If body is not executed,
the return value of exp-condition is returned. Because unless has no else branch, multiple
expressions in body do not need to be grouped
using begin. Examples: Notes: Description: Unpacks binary data into values according to a
specified format or a struct definition. When the first argument is a format string,
unpack decodes the binary data found in
str-addr-packed or at the memory address
num-addr-packed. This is the reverse operation
of pack. Using a numeric address allows unpacking data
returned from imported shared library functions. When the first argument is a struct symbol,
unpack uses the layout defined by the struct.
In this mode, alignment padding is handled
automatically according to data types and CPU
architecture. If num-addr-packed does not point to valid memory,
a bus error or segmentation fault may occur. When unpacking structures containing NULL pointers,
conversion to strings will raise an error. Use
void* in struct definitions when NULL pointers
are expected. Format specifiers: Examples: Notes: See: pack, struct,
address, get-int,
get-long, get-char,
get-string Description: Repeatedly evaluates body while exp-condition
evaluates to nil or the empty list (). Evaluation stops when exp-condition evaluates to
any value other than nil or (). The return value
of until is the result of the last expression
evaluated in body. If body is omitted, until repeatedly evaluates
exp-condition and returns its last value. until is functionally equivalent to: (while (not exp-condition) …) During execution, until updates the system
iterator symbol $idx. Examples: Notes: Description: Returns a copy of the string in str with all
characters converted to uppercase. International (UTF-8) characters are converted
correctly. The original string is not modified. Examples: Notes: See: lower-case,
title-case Description: Converts a UCS-4 (4-byte) Unicode-encoded string
into UTF-8. utf8 is the inverse operation of unicode. It is
only meaningful when UCS-4 encoded strings are in
use. On systems using UTF-8 natively, this function
is typically not required. When evaluated as a symbol, utf8 can also be used
to test whether UTF-8 support is available. On big-endian architectures, byte order is handled
accordingly during conversion. Examples: Notes: See: unicode,
lower-case,
upper-case Description: Returns the number of characters in a UTF-8 encoded
string. UTF-8 characters may consist of multiple bytes.
utf8len counts Unicode characters, not bytes. This
differs from length, which returns the number of
bytes in the string. This function is available only when UTF-8 support
is enabled. Examples: Notes: Description: Constructs and returns a UUID (Universally Unique
Identifier). When called without arguments, uuid returns a
randomly generated type 4 UUID. When the optional str-node argument is specified,
uuid returns a type 1 UUID derived from a timestamp
and node identifier. The node identifier may be a
valid MAC address of a network adapter or a randomly
generated node ID. When a random node ID is used, the least significant
bit of the first node byte should be set to 1 to
avoid collisions with real MAC addresses. UUID generation follows RFC 4122. Examples: Notes: Description: Waits for a child process to terminate and returns
its process identifier and termination status. The child process must have been created previously
using process or fork. When the specified child
terminates, wait-pid returns a list containing the
pid and a status value describing the reason for
termination. When int-pid is: The interpretation of the returned status value is
platform-specific. Consult the Unix documentation
for waitpid for details. An optional int-options argument may be supplied to
control behavior. When nil is specified instead of
int-options, wait-pid operates in non-blocking mode
and returns immediately. In this case, a pid value
of 0 indicates that no child process has terminated. Examples: Notes: See: process, fork,
sync, exit Description: Evaluates the expressions in body only when
exp-condition evaluates to a value other than
nil or the empty list (). If body is executed, the result of its last
expression is returned. If body is not executed,
nil or () is returned. Because when has no else branch, multiple
expressions in body do not need to be grouped
using begin. Examples: Notes: Description: Repeatedly evaluates body while exp-condition
evaluates to a value other than nil or the empty
list (). Evaluation stops when exp-condition evaluates to
nil or (). The return value of while is the result
of the last expression evaluated in body. During execution, while updates the system
iterator symbol $idx. Examples: Notes: Description: Writes data to a file, standard output, or appends
destructively to a string. When called with int-file, write outputs int-size
bytes from str-buffer to the file descriptor obtained
from open. If int-size is omitted, all data in
str-buffer is written. The function returns the
number of bytes written, or nil on failure. When called with a string as the first argument,
write appends data destructively to that string. When called without arguments, write writes the
contents of the last read-line to standard output
(STDOUT). write is a shorter form of write-buffer. The longer
name is deprecated and should be avoided in new code. Examples: Notes: Description: Writes one or more bytes to a file specified by
the file handle int-file. Each int-byte argument specifies an 8-bit byte
value to be written. The file handle must have
been obtained from a prior open operation. Each call to write-char advances the file pointer
by one byte per value written. The function returns
the number of bytes written. Examples: Notes: See: read-char, write,
copy-file, open Description: Writes the contents of str-buffer to a file specified
by str-file-name in a single operation. On success, write-file returns the number of bytes
written. On failure, nil is returned. When operating on local files, error details can be
retrieved using sys-error. When operating on URLs,
net-error provides additional error information. write-file can also write to URLs. When the filename
starts with http://, the function behaves like
put-url and supports the same additional parameters. Examples: Notes: See: read-file,
append-file,
put-url,
sys-error,
net-error Description: Writes a line to a device or appends a line to a
string. When int-file is specified, the string in str and
a line-termination character are written to the
file handle obtained from open. If str is omitted,
the contents of the last read-line are written. When both arguments are omitted, write-line writes
the last read-line to standard output (STDOUT) or
to the device currently set by device. When the first argument is a string, write-line
appends the string and a line terminator
destructively to that string. write-line returns the number of bytes written. Examples: Notes: See: write, read-line,
open, close Description: Registers a user-defined function to monitor byte
transfers during HTTP operations. The event handler is called whenever a block of data
is transferred by functions such as get-url,
post-url, put-url, or by file functions that operate
on URLs, including load, save, read-file, write-file,
and append-file. For each transferred data block, the handler function
is called with a single argument specifying the
number of bytes transferred. When xfer-event is called with nil, the transfer
event handler is reset to its default state. Examples: Notes: See: get-url, post-url,
put-url, read-file,
write-file Description: Returns error information from the last xml-parse
operation. If an error occurred during parsing, xml-error
returns a list containing two elements: If no error occurred, xml-error returns nil. Examples: Notes: See: xml-parse Description: Parses a string containing XML 1.0 compliant,
well-formed XML and returns a list structure. xml-parse does not perform DTD validation. Document
type declarations and processing instructions are
skipped. Nodes of type ELEMENT, TEXT, CDATA, and
COMMENT are parsed. If an element has no attributes or child nodes, an
empty list is returned for that element. Attributes
are returned as association lists and can be accessed
using assoc. When parsing fails due to malformed XML, xml-parse
returns nil and xml-error can be used to retrieve
error information. Examples: Options: The optional int-options argument controls how XML
input is translated. The following option values
can be combined by addition: Examples: Tag Translation: When option 8 is specified, XML tags are translated
from strings into symbols. The optional sym-context
parameter specifies the target context for symbol
creation. If omitted, the current context is used. If the specified context does not exist, it will be
created automatically. Examples: SXML Output: When xml-type-tags is configured to suppress XML
type tags and options 1, 2, 4, 8, and 16 are used,
xml-parse produces SXML-style output. Examples: Callback Processing: When func-callback is specified, xml-parse calls the
callback function after each tag is closed. The
callback receives three arguments: Examples: Notes: See: xml-error,
xml-type-tags Description: Controls suppression or translation of XML type tags
used by xml-parse. The XML type tags affected are: Each parameter specifies how the corresponding tag
is handled: xml-type-tags modifies only the tag names. It does
not suppress or alter the associated content. To
remove whitespace text nodes, empty attribute lists,
or comments, use option numbers in xml-parse. When called without arguments, xml-type-tags returns
the currently active type tags. Examples: Notes: See: xml-parse Description: Evaluates exp and returns true if the result is
the numeric value 0 (zero). Otherwise, nil is
returned. Both integer and floating-point zero are accepted.
For all non-numeric data types, zero? returns nil. Examples: Notes: Description: Computes the future value of a payment stream defined by
a constant interest rate, periodic fixed payments, and an
initial principal amount. When Examples: Notes: See: fin-irr, fin-nper,
fin-npv, fin-pmt,
fin-pv Description: Computes category probabilities for the tokens in Two compounding modes exist: When The returned list contains probability values in the same
order as the categories stored in Examples: 1. Classification using two short sample texts Token frequencies: Tokens similar to category A: Tokens similar to category B: 2. Chain Bayesian mode 3. Using direct probabilities Notes: See: sta-bayes-train, parse Description: Builds or updates a Bayesian dictionary inside the context
Only symbols and strings are used as valid tokens. String
tokens are converted into internal symbols by prepending
an underscore before insertion. A symbol named total is
created containing the total counts for each category. The dictionary produced by bayes-train is the data model
used by bayes-query. The order of categories in the lists
is the same order bayes-query uses when returning
probabilities. Training can occur in one or more stages. When the context
already contains trained data with the same number of
categories, new counts are added and totals updated. Relation to bayes-query Example: two small “documents” forming two categories These two lists define the categories A and B. Each token
will be counted and stored inside the dictionary Weather. The context Weather now contains token-frequency entries
for both categories: These frequencies form the exact model used by
Using the trained dictionary for classification The same model can now classify short texts: Tokens typical for category A: Tokens typical for category B: This demonstrates the complete cycle: Example: training with strings String tokens become symbols by prepending “_”. The
following example shows three categories, trained
simultaneously: Trained contexts can be used like hash tables: Explicit model construction without When the data set is small and token counts are known
directly, the model may be created manually without
training: Such data sets can still be evaluated using Multi-stage training Large corpora can be trained in several batches: Notes: See: sta-bayes-query, context Description: Computes the Beta function of two arguments and returned as a floating point number. The function is
typically used with positive real parameters. Examples: Notes: See: sta-gammaln Description: Computes the incomplete Beta function at point The cumulative binomial probability pev of an event with
probability p occurring k or more times in N trials can
be expressed as: Examples: Notes: See: sta-binomial, sta-beta Description: Computes the probability that an event with probability The value is returned as a floating point number. The
factorials follow standard integer factorial semantics,
and pow(x, y) denotes exponentiation. This function
represents the non-cumulative version of the binomial
distribution. Examples: Notes: Description: Computes the Pearson product-moment correlation between
two numerical vectors. Returned values: Examples: Description: Computes the critical Chi^2 value for a given confidence
probability and degrees of freedom. The returned number
is the threshold above which an observed Chi^2 statistic
would be considered significant under the null
hypothesis. This function is typically used in hypothesis testing to
find the cutoff point for Chi^2 distributions. A higher
probability yields a larger critical value. Examples: See: sta-prob-chi2 Description: Computes the critical value of the F distribution for a
given confidence probability. This function is used in variance comparisons and general
F-tests where the shape of the distribution depends on
two separate degrees of freedom. Examples: See: sta-prob-f Description: Computes the critical value of the Student t distribution
for a given confidence probability and degrees of
freedom. This function is commonly used in one-sample and
two-sample t-tests to determine whether the magnitude of
a t statistic is large enough to reject the null
hypothesis. Examples: See: sta-prob-t Description: Computes the critical value of the standard normal
distribution for a given cumulative probability.
Examples: See: sta-prob-z Description: Evaluates the normalized incomplete Gamma function for the
parameters num-a and num-b. The result is a floating-point
value in the range from 0 to 1. This function is commonly
used in probability calculations involving Chi-squared
distributions and related statistical measures. The probability that a Chi-squared statistic exceeds a
given value can be expressed using gammai as: Examples: Notes: See: prob-chi2 Description: Computes the natural logarithm of the Gamma function for
num-x. The Gamma function generalizes factorials to real
numbers, and gammaln provides a numerically stable way to
evaluate log(gamma(x)) for a wide domain of inputs. The relationship n! = gamma(n + 1) allows gammaln to be
used for factorial computations by exponentiating the
returned logarithmic value. The log Gamma function is also related to the Beta
function. The Beta function can be written in terms of
gammaln as: Examples: Notes: See: gammaisyntax: (mac (sym-name [sym-param-1 ...]) body)
syntax: (mac (sym-name [(sym-param-1 exp-default) ...]) body)
; 1) simple macro: (inc2 x) → (+ x 2)
(mac (inc2 x)
(+ (eval x) 2))
(inc2 10)
;-> 12
; 2) custom conditional form
; (if-zero x a b) → (if (= x 0) a b)
(mac (if-zero x a b)
(if (= (eval x) 0)
(eval a)
(eval b)))
(if-zero 0 "yes" "no")
;-> "yes"
(if-zero 5 "yes" "no")
;-> "no"
; 3) macro that defines a new function
; (make-fn name (p1) body) → (func (name p1) body)
(mac (make-fn name params body)
(func (name params) (eval body)))
(make-fn triple (x) (* x 3))
(triple 10)
;-> 30
; 4) macro with a default argument
; (add2 x) → (+ x 2)
(mac (add2 (x 0))
(+ (eval x) 2))
(add2 10)
;-> 12
(add2)
;-> 2
eval.
delete [!]
syntax: (delete symbol [bool])
syntax: (delete sym-context [bool])
nil.
When deleting a context, all symbols inside the context
are removed and the context name is converted into a
normal symbol containing nil. A second delete can remove
the context symbol itself.bool evaluates to true, deletion is allowed only when
the symbol has no external references. If bool evaluates
to nil, deletion is unconditional and reference checks are
skipped. This unconditional mode must be used with care:
if a deleted symbol is still referenced somewhere, the
missing update to nil can lead to crashes or inconsistent
program state.nil, and true
cannot be deleted. delete returns true on successful
deletion, or nil if deletion was refused.(set lst '(a b xvar c d))
;-> (a b xvar c d)
(delete 'xvar)
;-> true
lst
;-> (a b nil c d)
(set lst '(a b xvar c d))
;-> (a b xvar c d)
(delete 'xvar true)
;-> nil
lst
;-> (a b xvar c d)
(set ctx1:x 123)
;-> 123
(set ctx1:y "hello")
;-> "hello"
(delete 'ctx1)
;-> true
ctx1
;-> nil
fdel
syntax: (fdel str-file-name)
str-file-name. Returns true
when the file is successfully deleted, or nil if the
operation fails. When deleting a local file, error details
can be retrieved using syslasterr. When deleting a URL
resource, netlasterr provides additional information.urldel for
details.(fdel "temp.txt")
;-> true or nil
(fdel "http://example.com/sample.txt")
;-> true or nil
(fdel "file://notes.txt")
;-> true or nil
urldel
syntax: (urldel str-url)
str-url. The remote server must support the DELETE method
and allow deletion of the target resource; otherwise the
call returns nil or an error string. Optional parameters
such as timeouts or custom headers may be supplied in the
same way as with urlget.str-url begins with file://, a file on the local
filesystem is removed instead. This behavior matches
fdel when a URL is given.(urldel "http://example.com/data.txt")
;-> true or nil
(urldel "http://example.org:8080/page.html" 5000)
;-> true or nil
(urldel "file:///home/user/remove.txt")
;-> true or nil
urlget.
kill [!]
syntax: (kill int-pid)
syntax: (kill int-pid int-signal)
int-pid. When only int-pid is given, kill sends a
default fatal signal equivalent to SIGKILL. When
int-signal is supplied, the specified Unix signal is sent
instead. The function returns true on success or nil on
failure.fork or process.
kill operates exactly like the Unix kill utility and
obeys all standard semantics of process groups and user
permissions.
- If int-pid is 0, the signal is sent to all processes in
the caller’s process group.
- If int-pid is -1, the signal is sent to all processes
owned by the current user.
- Using these special values can terminate large numbers
of processes and should be used with extreme care.; start an external command
(set pid (process "/usr/bin/bc" in out))
;-> <pid>
(kill pid)
;-> true
; kill a forked background worker
(set pid (fork (repeat (i 1000)
(println i)
(sleep 10))))
;-> <pid>
(sleep 100)
(kill pid)
;-> true
kill can terminate process groups when specific PID
values (0 or -1) are used.
det
syntax: (mat-det matrix [float-pivot])
matrix. The matrix
may be given as a nested list or as an array. If the
matrix is singular and no pivot override is supplied, det
returns nil.float-pivot argument specifies a substitute
value for zero pivots during LU decomposition. This is
useful when working with singular or near-singular
matrices. A value of 0.0 forces all zero pivots to be
treated as exact zeros; very small values allow controlled
fallback behavior and prevent premature singularity
detection.(set A '((-1 1 1)
(1 4 -5)
(1 -2 0)))
;-> ((-1 1 1) (1 4 -5) (1 -2 0))
(mat-det A)
;-> -1
; singular matrices
(mat-det '((2 -1)
(4 -2)))
;-> nil
(mat-det '((2 -1)
(4 -2)) 0)
;-> -0
(mat-det '((2 -1)
(4 -2)) 1e-20)
;-> -4e-20
float-pivot influences LU decomposition when zero
pivots occur.nil.
device
syntax: (device [int-io-handle])
int-io-handle is supplied,
it becomes the new target for input and output.0 selects the default standard streams:- 0 — stdin
- 1 — stdout
- 2 — stderr
(device (open "myfile" "write"))
;-> 5
(print "This goes in myfile")
;-> "This goes in myfile"
(close (device))
;-> true
0.
diff
syntax: (diff list-1 list-2)
syntax: (diff list-1 list-2 bool)
list-1 but not in list-2. The input lists may contain
duplicates, but the result of this set operation is
unique.bool is true. All elements appearing in list-2 are removed
from list-1, while duplicates of remaining elements are
preserved.(diff '(2 5 6 0 3 5 0 2)
'(1 2 3 3 2 1))
;-> (5 6 0)
(diff '(2 5 6 0 3 5 0 2)
'(1 2 3 3 2 1)
true)
;-> (5 6 0 5 0)
list-2.
dir
syntax: (dir)
syntax: (dir str-path)
syntax: (dir str-path str-pattern [regex-option])
str-path. When str-path is omitted, entries from the
current working directory are returned. On failure, nil is
returned.str-pattern are included. When present,
regex-option controls the matching mode. Matching follows
the same rules as in rx function.(dir "/bin")
(dir "." "\\.c")
;-> ("file1.c" "file2.c")
(dir "." {\\.c})
;-> ("file1.c" "file2.c")
; show hidden entries
(dir "." "^[.]")
;-> ("." ".." ".conf" ".cache")
str-pattern uses standard regex syntax.regex-option enables specific rx evaluation modes.nil return indicates that the directory could not be
read.
dir?
syntax: (dir? str-path)
str-path refers to an existing directory.
Returns true when the path is a directory, or nil when it
is not.(dir? "/etc")
;-> true
(dir? "/usr/local/bin/nvi2/")
;-> nil
nil when the path does not exist or is not a
directory.
dircd
syntax: (dircd str-path)
str-path. When
the directory change succeeds, the function returns
true. If the path does not exist or cannot be used as a
working directory, the function returns nil. The change
affects all subsequent file-system operations performed
by the current Rebel process.(dircd "/etc")
div
syntax: (div num-1 num-2 [num-3 ...])
syntax: (div num-1)
(div 10 3)
;-> 3.333333333
(div 120 (sub 9.0 6) 100)
;-> 0.4
(div 10)
;-> 0.1
do
syntax: (do body)
body in sequence and returns
the value of the last one. do is used to group multiple
expressions where only a single expression is normally
allowed. It is commonly used inside conditional forms.cond, def,
doargs, dolist, dostring, when, and while
already accept multiple expressions in their bodies, but
do is useful in forms like if, where only one body
expression is permitted.silent function behaves like do but suppresses
console output from the final result.(do
(print "This is a block of 2 expressions\n")
(print "================================"))
body.silent is the same as do but without printed output.
do-until
syntax: (do-until exp-condition [body])
(set x 1)
(do-until (> x 0) (inc x))
;-> 2
(set x 1)
(until (> x 0) (inc x))
;-> 1
do-while
syntax: (do-while exp-condition body)
(set x 10)
(do-while (< x 10) (inc x))
;-> 11
(set x 10)
(while (< x 10) (inc x))
;-> 10
doargs
syntax: (doargs (sym [exp-break]) body)
sym is
bound to each argument in sequence. Iteration stops when
all arguments are processed or when exp-break evaluates to
a non-nil value. The return value is the final result of
evaluating body.$idx is
updated.; all arguments are unbound
(func (f)
(doargs (arg) (println arg)))
(f 1 2 3 4)
;-> prints:
1
2
3
4
; first two arguments are bound
(func (f a b)
(doargs (arg) (println arg)))
(f 1 2 3 4)
;-> prints:
3
4
; stop early when an argument equals 'x
(mac (g)
(doargs (arg (= arg 'x))
(println arg)))
(g a b x c d)
;-> prints:
a
b
true
exp-break is checked before each iteration step.$idx increments on each processed argument.args function or $args variable when the
full argument list is required at once.
dolist
syntax: (dolist (sym list-1|array-1 [exp-break]) body)
list-1 or array-1.
Before each iteration, sym is bound to the current element.
The binding is local to the loop and follows dynamic
scoping rules. The return value of dolist is the last value
produced by body, unless an early exit occurs.exp-break is present, it is evaluated before each
iteration step. When exp-break evaluates to a non-nil
value, the loop terminates immediately and returns that
value.$idx contains the
current index (starting at 0).(set x 123)
(dolist (x '(a b c d e f g))
(print x))
;-> g
; console output:
; abcdefg
; early exit when element equals 'e
(dolist (x '(a b c d e f g) (= x 'e))
(print x))
;-> true
; console output:
; abcd
; x outside the loop is unchanged
x
;-> 123
; show index and value
(dolist (x '(a b d e f g))
(println $idx ":" x))
;-> g
; console output:
; 0:a
; 1:b
; 2:d
; 3:e
; 4:f
; 5:g
sym is local to the loop.exp-break is evaluated before each iteration.$idx increments on each step and cannot be modified.
dostring
syntax: (dostring (sym string-1 [exp-break]) body)
string-1. Before every
iteration, sym is bound to the character’s integer code
point. The binding follows dynamic scoping rules and is
local to the loop.exp-break is present, it is evaluated before each
iteration step. When exp-break becomes non-nil, the loop
terminates immediately and returns its value. Otherwise,
body is evaluated and the loop continues.body. During
execution, the system iterator $idx contains the current
character index.; ASCII
(set str "abcdefg")
(dostring (c str)
(println c " " (char c)))
;-> prints:
; 97 a
; 98 b
; 99 c
; 100 d
; 101 e
; 102 f
; 103 g
; UTF-8
(set txt "我能吞下玻璃而不伤身体。")
(dostring (c txt)
(println c " " (char c)))
;-> prints codepoint and character for each element
$idx starts at zero and increments each iteration.
ls
syntax: (ls (sym sym-context [bool]) body)
ls loops over all symbols stored in sym-context.
Symbols are visited in sorted order. Before each
iteration, sym is bound to the next symbol. The
binding is local to the loop and follows dynamic
scoping rules. The return value is the last evaluation
of body.bool evaluates to non-nil, only symbols whose names
begin with an underscore (_) are included. This is useful
when a context contains internal keys or auxiliary data
under underscore-prefixed names.$idx contains the
current symbol index.; iterate through all symbols in a context
(ls (s ctx)
(print s " "))
; iterate only over symbols beginning with "_"
(ls (s ctx true)
(print s " "))
sym is local to the loop.$idx increments on each step.ls avoids the memory overhead of creating a list
using the symbols function.
dump
syntax: (dump)
syntax: (dump exp)
exp is supplied, it is
evaluated and the internal representation of the resulting
cell is returned as a list of integers.offset description
0 memory address of the cell
1 cell->type (major/minor type)
2 cell->next pointer
3 cell->aux
- string length + 1
- low/high word of 64-bit integer
- low word of IEEE 754 double
4 cell->contents
- string or symbol address
- high/low word of 64-bit integer
- high word of IEEE 754 double
(dump 'a)
;-> (9586996 5 9578692 9578692 9759280)
(dump 999)
;-> (9586996 130 9578692 9578692 999)
empty?
syntax: (empty? exp)
syntax: (empty? str)
exp is an empty list or whether str is an
empty string. Returns true when the argument contains no
elements; otherwise returns nil.(set lst '())
(empty? lst)
;-> true
(empty? '(1 2 3 4))
;-> nil
(empty? "hello")
;-> nil
(empty? "")
;-> true
nil are not considered empty lists.
encrypt
syntax: (encrypt str-source str-pad)
str-source
using the pad string in str-pad. The operation is
symmetric: applying the same pad to the encrypted output
restores the original data.; encrypt
(set msg (encrypt "A secret message" "my secret key"))
;-> ",YS\022\006\017\023\017TM\014\022\n\012\030E"
; decrypt by applying the same pad
(encrypt msg "my secret key")
;-> "A secret message"
; encrypt a file
(write-file "file.enc"
(encrypt (read-file "file.txt") "29kH67*"))
;-> true
ends-with
syntax: (ends-with str-data str-key [num-option])
syntax: (ends-with list exp)
; string matching
(ends-with "RebelLang" "Lang")
;-> true
(ends-with "RebelLang" "lang")
;-> nil
; regular expression form
(ends-with "RebelLang" "lang|test" 1)
;-> true
; list matching
(ends-with '(1 2 3 4 5) 5)
;-> true
(ends-with '(a b c d e) 'b)
;-> nil
(ends-with '(a b c (+ 3 4)) '(+ 3 4))
;-> true
env
syntax: (env)
syntax: (env var-str)
syntax: (env var-str value-str)
; retrieve entire environment
(env)
;-> (("PATH" "/usr/bin:/bin") ("TERM" "xterm") ...)
; read a variable
(env "PATH")
;-> "/usr/bin:/bin:/usr/local/bin"
; set a variable
(env "REBELDIR" "/usr/local/share/rebel")
;-> true
; read it back
(env "REBELDIR")
;-> "/usr/local/share/rebel"
; remove the variable
(env "REBELDIR" "")
;-> true
(env "REBELDIR")
;-> nil
erf
syntax: (erf num)
(map erf (sequence 0.0 6.0 0.5))
;-> (0
; 0.5204998778
; 0.8427007929
; 0.9661051465
; 0.995322265
; 0.999593048
; 0.9999779095
; 0.9999992569
; 0.9999999846
; 0.9999999998
; 1
; 1
; 1)
error-event
syntax: (error-event sym-event-handler)
syntax: (error-event func-event-handler)
syntax: (error-event nil)
(define (my-handler)
(print "error # " (first (last-error)) " occurred\n"))
(error-event 'my-handler)
;-> my-handler
; using the function directly
(error-event my-handler)
;-> $error-event
; using an inline function
(error-event
(fn ()
(print "error # " (first (last-error)) " occurred\n")))
;-> $error-event
; install exit as handler
(error-event exit)
;-> $error-event
; remove handler
(error-event nil)
;-> nil
etime
syntax: (etime exp [int-count])
exp and returns the time
spent on evaluation in floating point milliseconds.int-count is specified, exp is evaluated
int-count times and the total elapsed time is
returned.(etime (func x y z))
;-> 450.340
(etime (func x y z) 10)
;-> 4420.021
int-count is used, the reported time is the
sum of all evaluations.etime evaluates its argument normally.
eval
syntax: (eval exp)
; basic evaluation
(set expr '(+ 3 4))
expr
;-> (+ 3 4)
(eval expr)
;-> 7
(eval (list + 3 4))
;-> 7
(eval ''x)
;-> x
; evaluation uses current environment
(set x 3 'y 4)
(eval '(+ x y))
;-> 7
; local environment
(let ((x 33) (y 44))
(eval '(+ x y)))
;-> 77
; after leaving the local environment
(eval '(+ x y))
;-> 7
; passing data by reference using quoted symbols
(define (change-list aList)
(push 999 (eval aList)))
(set data '(1 2 3 4 5))
(change-list 'data)
;-> (999 1 2 3 4 5)
eval-string
syntax: (eval-string str-source [sym-context [exp-error [int-offset]]])
; basic evaluation
(eval-string "(+ 3 4)")
;-> 7
(set x 10)
(set y 20)
(eval-string "(+ x y)")
;-> 30
; evaluate in a different context
(context 'C)
(set C:x 2)
(set C:y 3)
(eval-string "(+ x y)" 'C)
;-> 5
; error handler expression
(eval-string "(+ 1 'a)"
MAIN
'"error")
;-> "error"
; start evaluating from an offset
(eval-string "(+ 1 2)(+ 3 4)" MAIN nil 7)
;-> 7
even?
syntax: (even? int-number)
(even? 123)
;-> nil
(even? 8)
;-> true
(even? 8.7)
;-> true
exec
syntax: (exec str-process)
syntax: (exec str-process str-stdin)
; capture output of a command
(exec "ls *.c")
;-> ("rebel.c" "math.c" "string.c")
; send standard input to a Unix program that reads stdin
(set str "line1\nline2\n")
(exec "wc -l" str)
;-> true
exists
syntax: (exists func-condition lst)
; first string in the list
(exists string? '(2 3 4 6 "hello" 7))
;-> "hello"
; no string present
(exists string? '(3 4 2 -7 3 0))
;-> nil
; find the first zero
(exists zero? '(3 4 2 -7 3 0))
;-> 0
; find the first negative number
(exists < '(3 4 2 -7 3 0))
;-> -7
; custom condition
(exists (fn (x) (> x 3)) '(3 4 2 -7 3 0))
;-> 4
; no match
(exists (fn (x) (= x 10)) '(3 4 2 -7 3 0))
;-> nil
exit
syntax: (exit)
syntax: (exit int)
(exit 5)
;-> process terminates with exit code 5
expand
syntax: (expand exp sym-1 [sym-2 ...])
syntax: (expand exp list-assoc [bool])
syntax: (expand exp)
; first syntax: expand bound variables
; ------------------------------------
(set x 2 'a '(d e))
(set val 'a)
(expand val 'a)
;-> (d e)
(expand '(a x b) 'x)
;-> (a 2 b)
(expand '(a x (b c x)) 'x 'a)
;-> ((d e) 2 (b c 2))
; dynamic function construction
(define (raise-to power)
(expand (fn (base) (pow base power)) 'power))
(set square (raise-to 2))
(set cube (raise-to 3))
(square 5)
;-> 25
(cube 5)
;-> 125
; second syntax: association list expansion
; -----------------------------------------
(expand '(a b c) '((a 1) (b 2)))
;-> (1 2 c)
(expand '(a b) '((a (+ 1 2)) (b (+ 3 4))))
;-> ((+ 1 2) (+ 3 4))
(expand '(a b) '((a (+ 1 2)) (b (+ 3 4))) true)
;-> (3 7)
; third syntax: uppercase-variable expansion
; ------------------------------------------
(set A 1 'Bvar 2 'C nil 'd 5)
(expand '(A (Bvar) C d))
;-> (1 (2) C d)
; simplified currying with uppercase variable
(define (raise-to Power)
(expand (fn (base) (pow base Power))))
(set cube (raise-to 3))
(cube 4)
;-> 64
explode [utf8]
syntax: (explode str [int-chunk [bool]])
syntax: (explode lst [int-chunk [bool]])
; string → characters
(explode "rebel")
;-> ("r" "e" "b" "e" "l")
; preserve original by joining back
(join (explode "keep it together"))
;-> "keep it together"
; string → fixed-width chunks
(explode "rebel" 2)
;-> ("re" "be" "l")
; omit incomplete chunk
(explode "rebel" 3 true)
;-> ("reb")
; binary handling on UTF-8 builds requires unpack
(set bytes "\001\002\003\004")
(unpack (dup "c" (length bytes)) bytes)
;-> (1 2 3 4)
; list → sublists
(explode '(a b c d e f g h))
;-> ((a) (b) (c) (d) (e) (f) (g) (h))
(explode '(a b c d e f g) 2)
;-> ((a b) (c d) (e f) (g))
; omit last short chunk
(explode '(a b c d e f g) 2 true)
;-> ((a b) (c d) (e f))
; works well with transpose
(transpose (explode '(a b c d e f g h) 2))
;-> ((a c e g) (b d f h))
; idiom: reverse a UTF-8 string safely
; reverse cannot operate on UTF-8 directly
(join (reverse (explode "žába")))
;-> "abáž"
extend [!]
syntax: (extend list-1 [list-2 ... ])
syntax: (extend string-1 [string-2 ... ])
; extending lists
(set lst '(a b))
(extend lst '(c d))
;-> (a b c d)
(extend lst '(e f g))
;-> (a b c d e f g)
lst
;-> (a b c d e f g)
; extending strings
(set str "ab")
(extend str "cd")
;-> "abcd"
(extend str "efg")
;-> "abcdefg"
str
;-> "abcdefg"
; extending nested elements in place
(set lst '(a b "CD" (e f)))
(extend (lst 2) "E")
lst
;-> (a b "CDE" (e f))
(extend (lst 3) '(g))
lst
;-> (a b "CDE" (e f g))
For a non-destructive alternative, use append.
factor
syntax: (factor int)
; basic factoring
(factor 123456789123456789)
;-> (3 3 7 11 13 19 3607 3803 52579)
; verify correctness
(= (apply * (factor 123456789123456789))
123456789123456789)
;-> true
; factoring the largest signed 64-bit integer
(factor 9223372036854775807)
;-> (7 7 73 127 337 92737 649657)
; small prime generator
(define (primes n , p)
(repeat (e n)
(if (= (length (factor e)) 1)
(push e p -1)))
p)
(primes 20)
;-> (2 3 5 7 11 13 17 19)
fappend
syntax: (fappend str-filename str-buffer)
str-buffer to the file specified
by str-filename. If the file does not yet exist, it is
created automatically and the function behaves like
fwrite. The return value is the number of bytes
written. On failure, the function returns nil.syserr can be queried
for additional information. When the target is a URL,
nlasterr provides extended diagnostics.fappend’ behaves like ‘hput’ with the
“Pragma: append\r\n” header automatically supplied. If
the remote file does not exist, it is created before the
append. This mechanism can also be used to transfer data
to remote Rebel nodes.(fwrite "myfile.txt" "ABC")
(fappend "myfile.txt" "DEF")
(fread "myfile.txt")
; → "ABCDEF"
(fappend "http://example.com/message.txt"
"More message text.")
nil on failure.hput.syserr (files) or nlasterr (URLs).
fcopy
syntax: (copy-file str-from-name str-to-name)
str-from-name into the path
specified by str-to-name. The function returns true when
the operation completes successfully. If the copy fails,
the result is nil. Failures may occur when the source
does not exist, the destination cannot be written, or an
I/O error interrupts the transfer.(fcopy "/home/me/rebel/data.rbl" "/tmp/data.rbl") ;-> true
fft
syntax: (fft list-num)
; basic forward/inverse identity
(ifft (fft '((1 0) (2 0) (3 0) (4 0))))
;-> ((1 0) (2 0) (3 0) (4 0))
; imaginary part defaults to 0
(fft '(1 2 3 4))
;-> ((10 0) (-2 -2) (-2 0) (-2 2))
; mixing plain numbers and explicit complex pairs
(fft '(1 2 (3 0) 4))
;-> ((10 0) (-2 -2) (-2 0) (-2 2))
file-info
syntax: (file-info str-name [int-index [bool-flag]])
index meaning
----- ----------------------------------------
0 size in bytes
1 mode (permissions + type)
2 device mode
3 user ID (owner)
4 group ID (owner group)
5 access time
6 modification time
7 status change time
; full metadata list
(file-info ".bashrc")
;-> (124 33188 0 500 0 920951022 920951022 920953074)
; select only one field
(file-info ".bashrc" 0)
;-> 124
; human-readable timestamp
(date (file-info "/etc" -1))
;-> "Mon Mar 8 18:23:17 2005"
file?
syntax: (file? str-path-name)
syntax: (file? str-path-name bool)
; exists (file or directory)
(file? "/usr/bin")
;-> true
; must be a regular file
(file? "/usr/bin/awk" true)
;-> "/usr/bin/awk"
(file? "/usr/bin" true)
;-> nil
; typical usage: prepare for opening a file
(if (file? "/tmp/data.txt")
(println "file exists"))
filter
syntax: (filter exp-predicate exp-list)
; basic predicate
(filter symbol? '(1 2 d 4 f g 5 h))
;-> (d f g h)
; user-defined predicate
(define (big? x) (> x 5))
(filter big? '(1 10 3 6 4 5 11))
;-> (10 6 11)
; using a comparison functor
(set lst '((a 10 2 7) (b 5) (a 8 3) (c 8) (a 9)))
(filter (curry match '(a *)) lst)
;-> ((a 10 2 7) (a 8 3) (a 9))
(filter (curry match '(? ?)) lst)
;-> ((b 5) (c 8) (a 9))
(filter (curry match '(* 8 *)) lst)
;-> ((a 8 3) (c 8))
difference, intersect
find
syntax: (find exp-key lst [func-compare | regex-option])
syntax: (find str-key str-data [regex-option [int-offset]])
; list search with plain comparison
(find '(1 2) '((1 4) 5 6 (1 2) (8 9)))
;-> 3
(find "world" '("hello" "world"))
;-> 1
(find "hi" '("hello" "world"))
;-> nil
; case-insensitive using regex option
(find "rebel" '("Rebel" "lang") "i")
;-> 0
$0
;-> "Rebel"
; comparison functor: find first element > key
(find 3 '(8 4 3 7 2 6) >)
;-> 4
$0
;-> 2
; custom comparison function
(define (has-last val item) (= val (last item)))
(find 22 '((a 3) (k 5) (z 22)) has-last)
;-> 2
$0
;-> (z 22)
; pattern match with match or unify
(find '(a ?) '((l 3) (a 10) (z 22)) match)
;-> 1
$0
;-> (a 10)
(find '(X X) '((a b) (c d) (e e)) unify)
;-> 2
$0
;-> (e e)
; string search
(find "world" "hello world")
;-> 6
(find "WORLD" "hello world")
;-> nil
; regex search (see regex for options)
(find "cat|dog" "I have a dog" 0)
;-> 9
$0
;-> "dog"
; search with offset
(find "cat|dog" "cat and dog" 0 5)
;-> 9
regex, find-all,
search, replace,
ref, ref-all
find-all
syntax: (find-all str-regex-pattern str-text [exp [regex-option]])
syntax: (find-all list-match-pattern lst [exp])
syntax: (find-all exp-key lst [exp [func-compare]])
; string search using regex
;----------------------------------------
(find-all {\d+} "x12y300z5")
;-> ("12" "300" "5")
$count
;-> 3
; process captures in a custom expression
;----------------------------------------
(find-all {(n)(um)} "numNUM" (append $2 $1) "i")
;-> ("umn" "UMN")
; use $count in the processing expression
;----------------------------------------
(find-all "a" "ababa" (string $count $it))
;-> ("1a" "2a" "3a")
; list pattern search using match
;----------------------------------------
(find-all '(? 2) '((a 1) (b 2) (a 2) (c 4)))
;-> ((b 2) (a 2))
$count
;-> 2
; process matched sublists
;----------------------------------------
(find-all '(? 2) '((a 1) (b 2) (a 2) (c 4)) (first $it))
;-> (b a)
; list search using a comparison function
;----------------------------------------
(find-all 5 '(2 7 4 5 9 2 4 9 7 4 8) $it <)
;-> (7 9 9 7 8)
$count
;-> 5
; process found elements
;----------------------------------------
(find-all 5 '(2 7 4 5 9 2 4 9 7 4 8) (* 3 $it) <)
;-> (21 27 27 21 24)
; same example using explicit fn
;----------------------------------------
(find-all 5 '(2 7 4 5 9 2 4 9 7 4 8)
(* 3 $it)
(fn (x y) (< x y)))
;-> (21 27 27 21 24)
; any expression may produce the result
;----------------------------------------
(find-all 5 '(2 7 4 5 9 2 4 9 7 4 8)
("abcdefghijk" $it)
<)
;-> ("h" "j" "j" "h" "i")
; using $count with list search
;----------------------------------------
(find-all 'a '(a b a b a b) (list $count $it))
;-> ((1 a) (2 a) (3 a))
first [utf8]
syntax: (first lst)
syntax: (first arr)
syntax: (first str)
; lists
(first '(1 2 3 4 5))
;-> 1
(first '((a b) c d))
;-> (a b)
(set lst '(a b c d e))
(first lst)
;-> a
; arrays
(set arr (array 3 2 (sequence 1 6)))
;-> ((1 2) (3 4) (5 6))
(first arr)
;-> (1 2)
; empty list
; (first '()) -> error
; strings (UTF-8 safe)
(first "rebel")
;-> "r"
(first (rest "rebel"))
;-> "e"
flat
syntax: (flat lst)
syntax: (flat lst int-level)
; full flatten
(flat '(a (b (c d))))
;-> (a b c d)
; using flat to walk nested structures
(map (fn (x) (ref x lst))
(flat '(a (b (c d)))))
;-> ((0) (1 0) (1 1 0) (1 1 1))
; partial flattening by level
;----------------------------------------
(flat '(a b (c d (e f)) (g h (i j))))
;-> (a b c d e f g h i j)
(flat '(a b (c d (e f)) (g h (i j))) 1)
;-> (a b c d (e f) g h (i j))
(flat '(a b (c d (e f)) (g h (i j))) 2)
;-> (a b c d e f g h i j)
; level 0 = no flattening
(flat '(a (b (c d))) 0)
;-> (a (b (c d)))
float
syntax: (float exp)
syntax: (float exp exp-default)
; basic parsing
(float "1.23")
;-> 1.23
(float " 1.23")
;-> 1.23
(float ".5")
;-> 0.5
(float "-1.23")
;-> -1.23
; invalid forms
(float "-.5")
;-> nil
(float "#1.23")
;-> nil
; default value
(float "#1.23" 0.0)
;-> 0.0
; non-numeric expressions
(float '(a b c))
;-> nil
(float '(a b c) 0)
;-> 0
(float nil 0)
;-> 0
; default value as non-numeric expression
(float "abc" "not a number")
;-> "not a number"
; overflow to infinity
(float "1e500")
;-> inf
(float "-1e500")
;-> -inf
; user input conversion
;----------------------------------------
; (print "enter a float: ")
; (set num (float (read-line)))
float?
syntax: (float? exp)
(set num 1.23)
(float? num)
;-> true
(float? 123)
;-> nil
(float? "1.23")
;-> nil
floor
syntax: (floor number)
(floor -1.5)
;-> -2
(floor 3.4)
;-> 3
flt
syntax: (flt number)
(flt 1.23)
;-> 1067282596
;; same encoding shown manually
(get-int (pack "f" 1.23))
;-> 1067282596
;; verify decode
(unpack "f" (pack "ld" (flt 1.2345)))
;-> (1.234500051)
fn
syntax: (fn (sym-1 [sym-2 ...]) body-1 [body-2 ...])
syntax: (fn (sym-1 [(sym-2 exp-default) ...]) body-1 [body-2 ...])
; basic anonymous function
(set f (fn (x) (+ x 1)))
(f 10)
;-> 11
; multiple parameters
(set add3 (fn (a b c) (+ a b c)))
(add3 1 2 3)
;-> 6
; default parameters
(set scale (fn (x (f 2)) (* x f)))
(scale 10)
;-> 20
(scale 10 5)
;-> 50
; variable arity using $args
(set sum-all (fn () (apply + $args)))
(sum-all 1 2 3 4 5)
;-> 15
; same using (args)
(set sum2 (fn () (apply + (args))))
(sum2 1 2 3 4 5)
;-> 15
fn-macro
syntax: (fn-macro (sym-1 [sym-2 ...]) body-1 [body-2 ...])
syntax: (fn-macro ((sym-1 exp-default-1) (sym-2 exp-default-2) ...) body-1 [body-2 ...])
; 1) simple macro: (inc2 x) → (+ x 2)
(set inc2
(fn-macro (x)
(+ (eval x) 2)))
(inc2 10)
;-> 12
; 2) custom conditional form
; (if-zero x a b) → (if (= x 0) a b)
(set if-zero
(fn-macro (x a b)
(if (= (eval x) 0)
(eval a)
(eval b))))
(if-zero 0 "yes" "no")
;-> "yes"
(if-zero 5 "yes" "no")
;-> "no"
; 3) macro that defines a new function
; (make-fn name (p1) body) → (define (name p1) body)
(set make-fn
(fn-macro (name params body)
(define (name params) (eval body))))
(make-fn triple (x) (* x 3))
(triple 10)
;-> 30
; 4) macro with a default argument
; (add2 x) → (+ x 2)
(set add2
(fn-macro ((x 0))
(+ (eval x) 2)))
(add2 10)
;-> 12
(add2)
;-> 2
for
syntax: (for (sym num-from num-to [num-step [exp-break]]) body)
;; simple increasing loop
(for (x 1 10)
(println x))
;-> prints 1 2 3 ... 10
;; custom step
(for (x 1 10 2)
(println x))
;-> prints 1 3 5 7 9
;; decreasing with fractional step
(for (x 8 6 0.5)
(println x))
;-> prints 8 7.5 7 6.5 6
;; break when a condition becomes true
(for (x 1 100 2 (> (* x x) 30))
(println x))
;-> prints 1 3 5
;-> returns true
;; generate a countdown list
(collect 'lst
(for (n 5 1)
(push n lst -1)))
lst
;-> (5 4 3 2 1)
for-all
syntax: (for-all func-condition list)
(for-all number? '(2 3 4 6 7))
;-> true
(for-all number? '(2 3 4 6 "hello" 7))
;-> nil
(for-all (fn (x) (= x 10)) '(10 10 10 10 10))
;-> true
;; check if all strings are ASCII-only
(for-all (fn (str) (= (length str)
(length (explode str))))
'("abc" "test" "X9"))
;-> true
fork
syntax: (fork exp)
; basic fork: parent and child diverge
;------------------------------------------------------------
(set x 0)
(fork
(while (< x 5)
(println (inc x))
(sleep 1000)))
;-> PID-of-child
; child prints:
;-> 1
;-> 2
;-> 3
;-> 4
;-> 5
x
;-> 0 ; parent unchanged
; communication using a Unix pipe
;------------------------------------------------------------
(map with '(read-end write-end) (pipe))
(define (counter n out)
(while (> n 0)
(write-line out (string n))
(dec n)))
(define (observer in)
(let (line)
(while (setq line (read-line in))
(println "count " line))))
(set child-observer (fork (observer read-end)))
(set child-counter (fork (counter 5 write-end)))
(wait-pid child-observer)
(wait-pid child-counter)
; destroying a long-running child
;------------------------------------------------------------
(define (demo)
(set pid
(fork
(repeat (i 1000)
(println i)
(sleep 20))))
(sleep 100)
(destroy pid))
(demo)
;-> prints numbers, child terminated
format
syntax: (format str-format exp-data-1 [exp-data-2 ... ])
syntax: (format str-format list-data)
"%w.pf"
w = optional width
p = optional precision
f = required type flag
(format ">>>%6.2f<<<" 1.2345)
;-> ">>> 1.23<<<"
(format "%e" 123456789)
;-> "1.234568e+08"
(format "Result = %05d" 2)
;-> "Result = 00002"
(format "%-15s" "hello")
;-> "hello "
(format "%5.2s" "hello")
;-> " he"
(format "%o" 80)
;-> "120"
(format "%x %X" -1 -1)
;-> "ffffffff FFFFFFFF"
(format "%c" 65)
;-> "A"
s text string
c character (1–255)
d decimal (32-bit)
u unsigned decimal (32-bit)
x hexadecimal lowercase
X hexadecimal uppercase
o octal
f floating point
e scientific notation (lowercase)
E scientific notation (uppercase)
g general floating point
ld signed decimal
lu unsigned decimal
lx hexadecimal
lX hexadecimal uppercase
lld signed decimal (long long)
llu unsigned decimal (long long)
llx hexadecimal (long long)
llX hexadecimal uppercase (long long)
(format "%14.2f" 12345678.12)
;-> " 12345678.12"
(format "%8d" 12345)
;-> " 12345"
(set lst '("hello" 123))
(format "%15s %d" lst)
;-> " hello 123"
(format "%f" 123)
;-> "123.000000"
(format "%d" 123.456)
;-> 123
freq
syntax: (freq list-1 list-2)
(freq '(1 2 3) '(3 2 1 4 2 3 1 1 2 2))
;-> (3 4 2)
(freq '(z a) '(z d z b a z y a))
;-> (3 2)
(set lst (explode (fread "myFile.txt")))
;-> list of characters
(set letter-counts (freq (uniq lst) lst))
;-> frequency data
func
syntax: (func (sym-name [sym-1 ...]) body-1 [body-2 ...])
func creates a named function in the current context
and returns the created function value. The returned
value is equivalent to an anonymous function created
with fn.sym-name becomes a function that accepts the
specified parameters and evaluates the body expressions
in order. The value of the last body expression is
returned.$args or via the function
(args).; basic named function
(func (increment x) (+ x 1))
(increment 10)
;-> 11
; multiple parameters
(func (add3 a b c) (+ a b c))
(add3 1 2 3)
;-> 6
; default parameters
(func (scale x (f 2)) (* x f))
(scale 10)
;-> 20
(scale 10 5)
;-> 50
; variable arity using $args
(func (sum-all) (apply + $args))
(sum-all 1 2 3 4 5)
;-> 15
; same using (args)
(func (sum2) (apply + (args)))
(sum2 1 2 3 4 5)
;-> 15
func creates a named function in the current context.
functor
syntax: (functor context)
context. The default functor is the symbol whose
name is identical to the context name. Many expressions
implicitly fall back to the default functor when a bare
context name appears; functor provides explicit access to
that value.(set ctx:ctx 123)
;-> 123
(functor ctx)
;-> 123
(set (functor ctx) 456)
;-> 456
(set c ctx)
;-> ctx
(functor c)
;-> 456
ctx:ctx
;-> 456
set or func
gcd
syntax: (gcd int-1 [int-2 ...])
(gcd 0)
;-> 0
(gcd 0 0)
;-> 0
(gcd 10)
;-> 10
(gcd 12 36)
;-> 12
(gcd 15 36 6)
;-> 3
get-char
syntax: (get-char int-address)
; Step 1: Create a small C file returning a pointer to bytes
;-----------------------------------------------------------
unsigned char *
make_bytes(void)
{
static unsigned char buf[] = "Hello";
return buf;
}
; Step 2: Compile it as a shared object (my.so)
;-----------------------------------------------------------
; cc -shared -fPIC -o my.so my.c
; Step 3: Import the function in Rebel
;-----------------------------------------------------------
(import "./my.so" "make_bytes")
; pointer returned by the C function
(make_bytes)
;-> 140737353912720 ; example address
; read bytes using get-char
(get-char (make_bytes))
;-> 72
(get-char (+ (make_bytes) 1))
;-> 101
get-float
syntax: (get-float int-address)
; Step 1: Create a small C file returning a pointer to a double
;-----------------------------------------------------------
double *
make_value(void)
{
static double val = 123.456;
return &val;
}
; Step 2: Compile it as a shared object (my.so)
;-----------------------------------------------------------
; cc -shared -fPIC -o my.so my.c
; Step 3: Import the function in Rebel
;-----------------------------------------------------------
(import "./my.so" "make_value")
; pointer returned by the C function
(make_value)
;-> 140737353912720 ; example address
; read the floating-point value
(get-float (make_value))
;-> 123.456
get-int
syntax: (get-int int-address)
; Step 1: Create a C file returning a pointer to a 32-bit integer
;-----------------------------------------------------------
int *
make_int(void)
{
static int val = 123;
return &val;
}
; Step 2: Compile it as a shared object (my.so)
;-----------------------------------------------------------
; cc -shared -fPIC -o my.so my.c
; Step 3: Import the function in Rebel
;-----------------------------------------------------------
(import "./my.so" "make_int")
; pointer returned by the C function
(make_int)
;-> 140737353912720 ; example address
; read the integer value
(get-int (make_int))
;-> 123
get-long
syntax: (get-long int-address)
; Step 1: Create a C file returning a pointer to a 64-bit integer
;-----------------------------------------------------------
long *
make_long(void)
{
static long val = 9876543210L;
return &val;
}
; Step 2: Compile it as a shared object (my.so)
;-----------------------------------------------------------
; cc -shared -fPIC -o my.so my.c
; Step 3: Import the function in Rebel
;-----------------------------------------------------------
(import "./my.so" "make_long")
; pointer returned by the C function
(make_long)
;-> 140737353912720 ; example address
; read the 64-bit integer value
(get-long (make_long))
;-> 9876543210
get-string
syntax: (get-string int-address [int-bytes [str-limit]])
; Step 1: Create a C file returning a pointer to a C string
;-----------------------------------------------------------
char *
make_bytes(void)
{
static char buf[] = "ABCDEFG";
return buf;
}
; Step 2: Compile it as a shared object (my.so)
;-----------------------------------------------------------
; cc -shared -fPIC -o my.so my.c
; Step 3: Import the function in Rebel
;-----------------------------------------------------------
(import "./my.so" "make_bytes")
; basic string read: stops at first zero byte
(get-string (make_bytes))
;-> "ABCDEFG"
; Step 4: Reading from a Rebel buffer
;-----------------------------------------------------------
(set buff "ABC\000\000\000DEF")
;-> "ABC\000\000\000DEF"
(get-string buff)
;-> "ABC"
; offset into the buffer
(get-string (+ (address buff) 6))
;-> "DEF"
; Step 5: Using int-bytes to read a fixed-length block
;-----------------------------------------------------------
(get-string buff 9)
;-> "ABC\000\000\000DEF"
; Step 6: Using a string limit
;-----------------------------------------------------------
(set buff2 "ABC\000\000EFG\000DQW")
(get-string buff2 4 "FG")
;-> "ABC\000"
(get-string buff2 10)
;-> "ABC\000\000EFG\000D"
(get-string buff2 10 "FG")
;-> "ABC\000\000E"
; Step 7: UTF-32 buffer with explicit terminator limit
;-----------------------------------------------------------
(set utf32 (unicode "我能吞下玻璃而不伤身体。"))
(set addr (address utf32))
(get-string utf32 80 "\000\000\000\000")
;-> a raw UTF-32 byte sequence up to the terminator
get-url
syntax: (get-url str-url [str-option] [int-timeout [str-header]])
; basic GET request
;-----------------------------------------------------------
(get-url "http://example.com")
; GET with timeout
;-----------------------------------------------------------
(get-url "http://example.com" 3000)
; request only the HTTP header
;-----------------------------------------------------------
(get-url "http://example.com" "header")
; header + timeout
;-----------------------------------------------------------
(get-url "http://example.com" "header" 5000)
; return (header body status-code)
;-----------------------------------------------------------
(get-url "http://example.com" "list")
; reading a local file via file://
;-----------------------------------------------------------
(get-url "file:///home/user/data.txt")
; custom header supplied by str-header
;-----------------------------------------------------------
(get-url "http://example.com" 5000
"User-Agent: Rebel\r\nCookie: test=1\r\n")
shared
syntax: (shared sym-1 [sym-2 ...])
MAIN can be made shared, and
the call to shared must also be executed from MAIN.
The function returns the last symbol processed.MAIN:. This mechanism is typically used for
sharing functions or constants from the MAIN context.; making several MAIN symbols shared
;-----------------------------------------------------------
(shared 'a 'x 'y 'z)
;-> z
; sharing a function and protecting it
;-----------------------------------------------------------
(func (f x) (+ x 1))
(const (shared 'f))
MAIN can be marked shared.shared must be executed in MAIN.
shared?
syntax: (shared? sym)
sym is shared. A symbol
is considered shared if it is visible without a context
prefix from other contexts. This includes built-in
functions and symbols and symbols explicitly marked
shared using the shared function. Returns true or
nil.; built-in functions are always shared
;-----------------------------------------------------------
(shared? 'print)
;-> true
; marking a symbol as shared
;-----------------------------------------------------------
(set val 123)
(shared 'val)
(shared? 'val)
;-> true
; sharing and protecting a symbol
;-----------------------------------------------------------
(set step 10)
(const (shared 'step))
(shared? 'step)
;-> true
true for all built-in functions and symbols.true for symbols shared via shared.
history
syntax: (history [bool-params])
; track calling functions
;-----------------------------------------------------------
(define (f1 x y)
(f2 (+ x 1) (* y 2)))
(define (f2 a b)
(history))
(f1 1 2)
;-> (f2 f1)
; include argument patterns
;-----------------------------------------------------------
(define (f2 a b)
(history true))
(f1 1 2)
;-> ((f2 (+ x 1) (* y 2)) (f1 1 2))
if
syntax: (if exp-condition exp-1 [exp-2])
syntax: (if exp-cond-1 exp-1 exp-cond-2 exp-2 [ ... ])
; basic conditional evaluation
;-----------------------------------------------------------
(set x 50)
(if (< x 100) "small" "big")
;-> "small"
(set x 1000)
(if (< x 100) "small" "big")
;-> "big"
; false branch absent: value of condition is returned
(if (> x 2000) "big")
;-> nil
; multiple expressions require begin
;-----------------------------------------------------------
(if (= x 10)
(begin
(println "true-branch")
(println x))
(begin
(println "false-branch")
(println x)))
; using the anaphoric variable $it
;-----------------------------------------------------------
(set lst '(A B C))
(if lst (println (last $it)))
;-> C
; multi-branch if
;-----------------------------------------------------------
(define (classify n)
(if
(< n 0) "negative"
(< n 10) "small"
(< n 20) "medium"
(>= n 30) "big"
"n/a"))
(classify 15)
;-> "medium"
(classify 100)
;-> "big"
(classify 22)
;-> "n/a"
(classify -10)
;-> "negative"
ifft
syntax: (ifft list-num)
; inverse transform of a real-valued sequence
;-----------------------------------------------------------
(ifft (fft '((1 0) (2 0) (3 0) (4 0))))
;-> ((1 0) (2 0) (3 0) (4 0))
; imaginary part defaults to 0.0 when plain numbers are used
;-----------------------------------------------------------
(ifft (fft '(1 2 3 4)))
;-> ((1 0) (2 0) (3 0) (4 0))
import
syntax: (import str-lib-name str-function-name)
syntax: (import str-lib-name str-function-name str-return-type [str-param-type ...])
syntax: (import str-lib-name)
label C type (LP64) Rebel type
---------------------------------------------------------------------------
"void" void nil
"byte" unsigned char (8 bit) integer
"char" signed char (8 bit) integer
"unsigned short" unsigned short (16 bit) integer
"short" short (16 bit) integer
"unsigned int" unsigned int (32 bit) integer
"int" int (32 bit) integer
"long" long (64 bit) integer
"long long" long long (64 bit) integer
"float" float (32 bit) 64-bit float (cut to 32)
"double" double (64 bit) 64-bit float
"char*" char* pointer string buffer or return string
"void*" void* pointer integer address
; import printf with simple syntax
;-----------------------------------------------------------
(import "/usr/lib/libc.so" "printf")
(printf "hello %d\n" 123)
;-> 10
; import strcpy with explicit type labels
;-----------------------------------------------------------
(import "/usr/lib/libc.so" "strcpy" "char*" "char*" "char*")
(set src "hello world")
(set dst (dup "\000" (length src)))
(strcpy dst src)
;-> "hello world"
; load a library without importing symbols
;-----------------------------------------------------------
(import "/usr/local/lib/libm.so")
; function returning a double
;-----------------------------------------------------------
(import "/usr/lib/libc.so" "atof" "double" "char*")
(atof "3.141")
;-> 3.141
; returning a raw pointer (void*)
;-----------------------------------------------------------
(import "/usr/lib/libc.so" "strcpy" "void*" "char*" "char*")
(set buf (dup "\000" 32))
(strcpy buf "test")
;-> an address number
(get-string buf)
;-> "test"
inc
syntax: (inc place [num])
(set x 0) ;-> 0
(inc x) ;-> 1
x ;-> 1
(inc x 0.25) ;-> 1.25
x ;-> 1.25
(inc x) ;-> 2.25
z ;-> nil
(inc z) ;-> 1
(set z nil)
(inc z 0.01) ;-> 0.01
(set l '(1 2 3 4))
(inc (l 3) 0.1) ;-> 4.1
(inc (first l)) ;-> 2
l ;-> (2 2 3 4.1)
(inc (+ 3 4)) ;-> 8
index
syntax: (index exp-predicate exp-list)
(index symbol? '(1 2 d 4 f g 5 h))
;-> (2 4 5 7)
(define (big? x) (> x 5))
;-> (fn (x) (> x 5))
(index big? '(1 10 3 6 4 5 11))
;-> (1 3 6)
inf?
syntax: (inf? float)
(inf? (div 1 0))
;-> true
(div 0 0)
;-> NaN
int
syntax: (int exp [exp-default [int-base]])
(int "123") ;-> 123
(int " 123") ;-> 123
(int "a123" 0) ;-> 0
(int (trim " 123")) ;-> 123
(int "0xFF") ;-> 255
(int "0b11111") ;-> 31
(int "055") ;-> 45
(int "1.567") ;-> 1
(int 1.567) ;-> 1
(integer? 1.00) ;-> nil
(integer? (int 1.00)) ;-> true
(int "1111" 0 2) ;-> 15
(int "0FF" 0 16) ;-> 255
(int 'xyz) ;-> nil
(int 'xyz 0) ;-> 0
(int nil 123) ;-> 123
(int "abc" (throw-error "not a number"))
;-> ERR: user error : not a number
(print "Enter a num:")
(set num (int (read-line)))
(int (bits 12345) 0 2) ;-> 12345
integer?
syntax: (integer? exp)
(set num 123) ;-> 123
(integer? num) ;-> true
(integer? 3.0) ;-> nil
(integer? (int 3.0)) ;-> true
invert
syntax: (invert matrix [float-pivot])
(set m1 '((-1 1 1) (1 4 -5) (1 -2 0)))
(invert m1)
;-> ((10 2 9) (5 1 4) (6 1 5))
(invert (invert m1))
;-> ((-1 1 1) (1 4 -5) (1 -2 0))
; solve m1 * x = b
(multiply (invert m1) '((1) (2) (3)))
;-> ((41) (19) (23))
; singular matrix handling
(invert '((2 -1) (4 -2)))
;-> nil
(invert '((2 -1) (4 -2)) 0.0)
;-> ((inf -inf) (inf -inf))
(invert '((2 -1) (4 -2)) 1e-20)
;-> ((5e+19 -2.5e+19) (1e+20 -5e+19))
irr
syntax: (irr list-amounts [list-times [num-guess]])
(irr '(-1000 500 400 300 200 100))
;-> 0.2027
(npv 0.2027 '(500 400 300 200 100))
;-> 1000.033848
(irr '(-1000 500 400 300 200 100) '(0 3 4 5 6 7))
;-> 0.0998
(irr '(-5000 -2000 5000 6000) '(0 3 12 18))
;-> 0.0321
json-error
syntax: (json-error)
; failed parse returns nil
(json-parse "{\"address\" \"http://example.com\"}")
;-> nil
; inspect error info from previous failure
(json-error)
;-> ("missing : colon" 11)
join
syntax: (join list-of-strings [str-joint [bool-trail-joint]])
(set lst '("this" "is" "a" "sentence"))
(join lst " ")
;-> "this is a sentence"
(join (map string (slice (now) 0 3)) "-")
;-> "2003-11-26"
(join (explode "keep it together"))
;-> "keep it together"
(join '("A" "B" "C") "-")
;-> "A-B-C"
(join '("A" "B" "C") "-" true)
;-> "A-B-C-"
kmeans-query
syntax: (kmeans-query list-data matrix-centroids)
syntax: (kmeans-query list-data matrix-data)
; centroids from previous kmeans-train
K:centroids
;-> ((6.39 7.188333333 5.935)
;-> (7.925714286 3.845714286 9.198571429)
;-> (2.207142857 2.881428571 0.8885714286))
(kmeans-query '(1 2 3) K:centroids)
;-> (8.036487279 9.475994267 2.58693657)
; smallest distance corresponds to centroid #3
; distances to all original data points
(kmeans-query '(1 2 3) data)
;-> (10.91671196 3.190626898 9.19723328 3.014415366 9.079763213
;-> 6.83130295 8.533111976 9.624816881 6.444261013 2.013107051
;-> 3.186549858 9.475199206 9.32936761 2.874786949 7.084638311
;-> 10.96221237 10.50080473 3.162419959 2.423674896 9.526436899)
; filter distances by cluster membership
; cluster 1
(select (kmeans-query '(1 2 3) data) (K:clusters 0))
;-> (9.079763213 6.83130295 9.624816881 6.444261013 7.084638311 10.50080473)
; cluster 2
(select (kmeans-query '(1 2 3) data) (K:clusters 1))
;-> (10.91671196 9.19723328 8.533111976 9.475199206 9.32936761
;-> 10.96221237 9.526436899)
; cluster 3
(select (kmeans-query '(1 2 3) data) (K:clusters 2))
;-> (3.190626898 3.014415366 2.013107051 3.186549858
;-> 2.874786949 3.162419959 2.423674896)
last
syntax: (last list)
syntax: (last array)
syntax: (last str)
(last '(1 2 3 4 5))
;-> 5
(last '(a b (c d)))
;-> (c d)
(set A (array 3 2 (sequence 1 6)))
;-> ((1 2) (3 4) (5 6))
(last A)
;-> (5 6)
(last '())
;-> ERR: list is empty
(last "rebel")
;-> "l"
last-error
syntax: (last-error)
syntax: (last-error int-error)
(last-error)
;-> nil
(abc)
;-> ERR: invalid function : (abc)
(last-error)
;-> (24 "ERR: invalid function : (abc)")
(last-error 24)
;-> (24 "invalid function")
(last-error 1)
;-> (1 "not enough memory")
(last-error 12345)
;-> (12345 "Unknown error")
legal?
syntax: (legal? str)
(symbol? (sym "one two"))
;-> true
(legal? "one two")
;-> nil
(set (sym "one two") 123)
;-> 123
(eval (sym "one two"))
;-> 123
length
syntax: (length exp)
; list length
(length '(a b (c d) e))
;-> 4
(length '())
;-> 0
(set lst '(q w e r t y))
;-> (q w e r t y)
(length lst)
;-> 6
; array length (rows)
(set arr (array 2 4 '(0)))
;-> ((1 2) (3 4) (5 6) (7 8)) ; example filler changed by array rules
(length arr)
;-> 2
; byte length of strings
(length "Hello World")
;-> 11
(length "")
;-> 0
(length "\000\001\003")
;-> 3
; symbol name length in bytes
(length 'someVar)
;-> 7
; digit count of numbers
(length 0)
;-> 0
(length 123)
;-> 3
(length 1.23)
;-> 1
(length 1234567890123456789012345L)
;-> 25
let
syntax: (let ((sym1 [exp-init1]) [(sym2 [exp-init2]) ... ]) body)
syntax: (let (sym1 exp-init1 [sym2 exp-init2 ... ]) body)
(define (sum-sq a b)
(let ((x (* a a)) (y (* b b)))
(+ x y)))
;-> (fn (a b) ...)
(sum-sq 3 4)
;-> 25
; alternative syntax
(define (sum-sq a b)
(let (x (* a a) y (* b b))
(+ x y)))
;-> (fn (a b) ...)
letex
syntax: (letex ((sym1 [exp-init1]) [(sym2 [exp-init2]) ... ]) body)
syntax: (letex (sym1 exp-init1 [sym2 exp-init2 ... ]) body)
(letex (x 1 y 2 z 3) '(x y z))
;-> (1 2 3)
(letex ((x 1) (y '(a b c)) (z "hello")) '(x y z))
;-> (1 (a b c) "hello")
; building a closure
(define (make-adder n)
(letex (c n)
(fn (x) (+ x c))))
(define add3 (make-adder 3))
;-> (fn (x) (+ x 3))
(add3 10)
;-> 13
; expansion into the same symbol
(define (make-adder n)
(letex (n n)
(fn (x) (+ x n))))
letn
syntax: (letn ((sym1 [exp-init1]) [(sym2 [exp-init2]) ... ]) body)
syntax: (letn (sym1 exp-init1 [sym2 exp-init2 ... ]) body)
(set x 10)
(let ((x 1) (y (+ x 1)))
(list x y))
;-> (1 11)
(letn ((x 1) (y (+ x 1)))
(list x y))
;-> (1 2)
(letn (x 1 y x)
(+ x y))
;-> 2
; equivalent nested lets
(let (x 1)
(let (y x)
(+ x y)))
;-> 2
list
syntax: (list exp-1 [exp-2 ... ])
(list 1 2 3 4 5)
;-> (1 2 3 4 5)
(list 'a '(b c) (+ 3 4) '() '*)
;-> (a (b c) 7 () *)
list?
syntax: (list? exp)
(set var '(1 2 3 4))
;-> (1 2 3 4)
(list? var)
;-> true
(define (double x) (+ x x))
;-> (fn (x) (+ x x))
(list? double)
;-> true
load
syntax: (load str-file-name-1 [str-file-name-2 ... ] [sym-context])
(load "file.rbl")
(load "a.rbl" "b.rbl")
(load "file.rbl" "http://example.org/mod")
(load "http://192.168.0.21:6000//home/test/program.rbl")
; load into a specific context
(load "alpha.rbl" "beta.rbl" 'ctx)
; file:// form uses three slashes before the path
(load "file:///usr/local/share/rebel/module.rbl")
local
syntax: (local (sym-1 [sym-2 ... ]) body)
(local (a b c)
(list a b c))
;-> (nil nil nil)
; localizing a variable that already has a value
(set x 42)
;-> 42
(local (x)
(+ x 1))
;-> 1
x
;-> 42
log
syntax: (log num)
syntax: (log num num-base)
(log 1)
;-> 0
(log (exp 1))
;-> 1
(log 1024 2)
;-> 10
(log (exp 1) (exp 1))
;-> 1
lookup
syntax: (lookup exp-key list-assoc [int-index [exp-default]])
(set params '(
(name "Alice")
(age 35)
(role "admin")
(balance 12.34)
))
(lookup 'age params)
;-> 35
; modify values using setf + lookup
(setf (lookup 'age params) 40)
;-> 40
(lookup 'age params)
;-> 40
; table of records
(set records '(
("Alice" 35 "admin" 12.34)
("Bob" 50 "user" 99.5)
))
(lookup "Bob" records 2)
;-> "user"
(lookup "Bob" records -3)
;-> 50
(lookup "Alice" records 1)
;-> 35
(lookup "Alice" records -2)
;-> "admin"
(lookup "Charlie" records 1 "N/A")
;-> "N/A"
lower-case [utf8]
syntax: (lower-case str)
(lower-case "HELLO WORLD")
;-> "hello world"
(set str "ABC")
;-> "ABC"
(lower-case str)
;-> "abc"
str
;-> "ABC"
macro
syntax: (macro (sym-name [sym-param-1 ...]) [body-1 ...])
; 1) simple expansion macro: (double X) → (+ X X)
(macro (double X)
(+ X X))
(double 10)
;-> 20
(read-expr "(double 7)")
;-> (+ 7 7)
; 2) swap two variables by expanding the call into assignments
(macro (swap A B)
(begin
(set A B)
(set B A)))
(set x 3 'y 9)
(swap x y)
(list x y)
;-> (9 3)
; 3) clamp value into a range using pure syntax expansion
(macro (clamp V LO HI)
(if (< V LO) LO
(if (> V HI) HI
V)))
(clamp 15 0 10)
;-> 10
(clamp -3 0 10)
;-> 0
(clamp 7 0 10)
;-> 7
macro?
syntax: (macro? exp)
; runtime macro
(define-macro (mysetq lv rv)
(set lv (eval rv)))
(macro? mysetq)
;-> true
; expansion macro
(macro (my-setq Lv Rv)
(set Lv Rv))
(macro? my-setq)
;-> true
(macro? 'my-setq)
;-> true
; non-macro values
(macro? 123)
;-> nil
(macro? +)
;-> nil
make-dir
syntax: (make-dir str-dir-name [int-mode])
; basic usage
;------------------------------------------------------------
(make-dir "adir")
;-> true
; explicit access mode (octal)
;------------------------------------------------------------
; leading zero denotes an octal number
(make-dir "secure-dir" 0750)
;-> true
map
syntax: (map exp-functor list-args-1 [list-args-2 ... ])
; basic mapping with multiple argument lists
;------------------------------------------------------------
(map + '(1 2 3) '(50 60 70))
;-> (51 62 73)
(map if '(true nil true nil true)
'(1 2 3 4 5)
'(6 7 8 9 10))
;-> (1 7 3 9 5)
(map (fn (x y) (* x y)) '(3 4) '(20 10))
;-> (60 40)
; generating a function dynamically
;------------------------------------------------------------
(define (make-adder n)
(fn (x) (+ n x)))
(map (make-adder 2) '(1 2 3 4 5))
;-> (3 4 5 6 7)
(define (make-multiplier n)
(fn (x) (* n x)))
(map (make-multiplier 3) '(1 2 3 4 5))
;-> (3 6 9 12 15)
; embedding map into a higher-level function
;------------------------------------------------------------
(define (map-with op p lst)
(map (fn (x) (op p x)) lst))
(map-with + 2 '(1 2 3 4))
;-> (3 4 5 6)
(map-with * 1.5 '(1 2 3 4))
;-> (1.5 3 4.5 6)
; access to the internal index
;------------------------------------------------------------
(map (fn (x) (list $idx x)) '(a b c))
;-> ((0 a) (1 b) (2 c))
mat
syntax: (mat + | - | * | / matrix-A matrix-B)
syntax: (mat + | - | * | / matrix-A number)
; matrix-to-matrix operations
;------------------------------------------------------------
(set A '((1 2 3) (4 5 6)))
(set B A)
(mat + A B)
;-> ((2 4 6) (8 10 12))
(mat - A B)
;-> ((0 0 0) (0 0 0))
(mat * A B)
;-> ((1 4 9) (16 25 36))
(mat / A B)
;-> ((1 1 1) (1 1 1))
; operator supplied as a variable
;------------------------------------------------------------
(set op +)
(mat op A B)
;-> ((2 4 6) (8 10 12))
; matrix-to-scalar operations
;------------------------------------------------------------
(mat + A 5)
;-> ((6 7 8) (9 10 11))
(mat - A 2)
;-> ((-1 0 1) (2 3 4))
(mat * A 3)
;-> ((3 6 9) (12 15 18))
(mat / A 10)
;-> ((0.1 0.2 0.3) (0.4 0.5 0.6))
match
syntax: (match list-pattern list-match [bool])
; simple element capture
;------------------------------------------------------------
(match '(a ? c) '(a b c))
;-> (b)
(match '(a ? ?) '(a b c))
;-> (b c)
(match '(a ? c) '(a (x y z) c))
;-> ((x y z))
(match '(a ? c) '(a (x y z) c) true)
;-> (a (x y z) c)
(match '(a ? c) '(a x y z c))
;-> nil
; list capture with *
;------------------------------------------------------------
(match '(a * c) '(a x y z c))
;-> ((x y z))
(match '(a (b c ?) x y z) '(a (b c d) x y z))
;-> (d)
(match '(a (*) x ? z) '(a (b c d) x y z))
;-> ((b c d) y)
; behavior of + and *
;------------------------------------------------------------
(match '(+) '())
;-> nil
(match '(+) '(a))
;-> ((a))
(match '(+) '(a b))
;-> ((a b))
(match '(a (*) x ? z) '(a () x y z))
;-> (() y)
(match '(a (+) x ? z) '(a () x y z))
;-> nil
; binding matched values
;------------------------------------------------------------
(map with '(x y)
(match '(a (? c) d *) '(a (b c) d e f)))
x
;-> b
y
;-> (e f)
max
syntax: (max num-1 [num-2 ... ])
(max 4 6 2 3.54 7.1)
;-> 7.1
(max 10 -5 3)
;-> 10
(max 2)
;-> 2
member
syntax: (member exp list)
syntax: (member str-key str [num-option])
(set lst '(a b c d e f g h))
;-> (a b c d e f g h)
(member 'd lst)
;-> (d e f g h)
(member 55 lst)
;-> nil
(member "REBEL" "HelloREBEL")
;-> "REBEL"
(member "RE" "HelloREBEL")
;-> "REBEL"
(member "" "HelloREBEL")
;-> "HelloREBEL"
(member "xyz" "HelloREBEL")
;-> nil
(member "re" "HelloREBEL" 1)
;-> "REBEL"
memcpy
syntax: (memcpy int-from-address int-to-address int-bytes)
int-bytes of raw memory from int-from-address to
int-to-address.memcpy can read from or write to arbitrary memory
locations, including memory associated with Rebel
values and internal cells.; The example copies three bytes from a string literal
; into the memory backing an existing string value.
(set s "0123456789") ;-> "0123456789"
(memcpy "xxx" (+ (address s) 5) 3)
s ;-> "01234xxx89"
memcpy exposes raw memory manipulation.
min
syntax: (min num-1 [num-2 ... ])
(min 4 6 2 3.54 7.1)
;-> 2
(min 10 -5 3)
;-> -5
(min 2)
;-> 2
mod
syntax: (mod num-1 num-2 [num-3 ... ])
syntax: (mod num-1)
(mod 10.5 3.3)
;-> 0.6
(mod -10.5 3.3)
;-> -0.6
(mod -10.5)
;-> -0.5
mstime
syntax: (mstime)
(mstime)
;-> 45238765
mul
syntax: (mul num-1 num-2 [num-3 ... ])
(mul 1 2 3 4 5 1.1)
;-> 132
(mul 0.5 0.5)
;-> 0.25
multiply
syntax: (multiply matrix-A matrix-B)
(set A '((1 2 3) (4 5 6)))
(set B '((1 2) (1 2) (1 2)))
(multiply A B)
;-> ((6 12) (15 30))
(set v '(10 20 30))
(multiply A (transpose (list v)))
;-> ((140) (320))
NaN?
syntax: (NaN? float)
; floating-point operations on NaN yield NaN
(set x (sqrt -1))
;-> -nan
(NaN? x)
;-> true
(add x 123)
;-> -nan
(mul x 123)
;-> -nan
; integer operations treat NaN as zero
(+ x 123)
;-> 123
(* x 123)
;-> 0
; comparisons with NaN yield nil
(> x 0)
;-> nil
(<= x 0)
;-> nil
(= x x)
;-> nil
(set infinity (mul 1.0e200 1.0e200))
;-> inf
(NaN? (sub infinity infinity))
;-> true
net-accept
syntax: (net-accept int-socket)
(set sock (net-listen 1234))
;-> <socket>
(net-accept sock)
;-> <socket>
net-close
syntax: (net-close int-socket [true])
(net-close sock)
;-> true
net-connect
syntax: (net-connect str-remote-host int-port [int-timeout-ms])
syntax: (net-connect str-remote-host int-port [str-mode [int-ttl]])
syntax: (net-connect str-file-path)
; TCP
(set sock (net-connect "example.org" 80))
;-> <socket>
; timeout
(net-connect "example.org" 22 500)
;-> <socket>|nil
; UDP
(net-connect "226.0.0.1" 4096 "udp")
;-> <socket>
; UDP multicast
(net-connect "" 4096 "multi")
;-> <socket>
; UDP broadcast
(net-connect "192.168.2.255" 3000 "broadcast")
;-> <socket>
; local domain socket
(net-connect "/tmp/rebel.sock")
;-> <socket>
net-error
syntax: (net-error)
syntax: (net-error int-error)
no description
-- ------------------------------------------------
1 Cannot open socket
2 DNS resolution failed
3 Not a valid service
4 Connection failed
5 Accept failed
6 Connection closed
7 Connection broken
8 Socket send() failed
9 Socket recv() failed
10 Cannot bind socket
11 Too many sockets in net-select
12 Listen failed
13 Badly formed IP
14 Select failed
15 Peek failed
16 Not a valid socket
17 Cannot unblock socket
18 Operation timed out
19 HTTP badly formed URL
20 HTTP file operation failed
21 HTTP transfer failed
22 HTTP invalid response from server
23 HTTP no response from server
24 HTTP no content
25 HTTP error in header
26 HTTP error in chunked format
(net-error)
;-> nil
(net-connect "jhghjgkjhg" 80)
;-> nil
(net-error)
;-> (2 "DNS resolution failed")
(net-error 10)
;-> (10 "Cannot bind socket")
net-eval
syntax: (net-eval str-host int-port exp [int-timeout [func-handler]])
syntax: (net-eval '((str-host int-port exp) ... ) [int-timeout [func-handler]])
(net-eval "192.168.1.94" 7306 '(+ 3 4))
;-> 7
(net-eval "192.168.1.94" 7306 "(+ 3 4)")
;-> 7
(net-eval "192.168.1.94" 7306 '(+ 3 4) 1)
;-> nil
(net-error)
;-> (18 "Operation timed out")
(net-eval "/tmp/rebel.sock" 0 '(+ 3 4))
;-> 7
(net-eval '(
("192.168.1.94" 7306 '(+ 3 4))
("192.168.1.95" 7306 '(+ 5 6))
) 5000)
;-> (7 11)
(define (handler msg)
(if msg
(println msg))
)
(net-eval '(
("192.168.1.94" 7306 '(+ 3 4))
("192.168.1.95" 7306 '(+ 5 6))
) 5000 handler)
net-interface
syntax: (net-interface str-ip-addr)
syntax: (net-interface)
(net-interface "192.168.1.95")
;-> "192.168.1.95"
(net-interface "localhost")
;-> "127.0.0.1"
(net-interface)
;-> "127.0.0.1"
net-ipv
syntax: (net-ipv int-version)
syntax: (net-ipv)
(net-ipv)
;-> 4
(net-ipv 6)
;-> 6
(net-ipv)
;-> 6
net-listen
syntax: (net-listen int-port [str-ip-addr [str-mode]])
syntax: (net-listen str-file-path)
(set port 7306)
(set listen (net-listen port))
(unless listen
(exit))
(set conn (net-accept listen))
(if conn
(while (net-receive conn buff 1024 "\n")
(print buff)
(if (= buff "\r\n") (exit))))
(net-listen "/tmp/rebel.sock")
;-> <socket>
(net-accept <socket>)
;-> <socket>
(net-listen 10002 "" "udp")
;-> <socket>
(net-receive-from <socket> 1024)
(net-listen 4096 "226.0.0.1" "multi")
;-> <socket>
(net-receive-from <socket> 1024)
net-local
syntax: (net-local int-socket)
(net-local sock)
;-> ("204.179.131.73" 1689)
net-lookup
syntax: (net-lookup str-ip-number)
syntax: (net-lookup str-hostname [bool])
(net-lookup "example.com")
;-> "23.220.75.232"
(net-lookup "23.220.75.232")
;-> "a23-220-75-232.deploy.static.akamaitechnologies.com"
net-packet
syntax: (net-packet str-packet)
; UDP packet with zeroed checksums (recalculated internally)
(set pkt (pack (dup "b" 39) '(
0x45 0x00 0x00 0x27 0x4b 0x8f 0x00 0x00 0x40 0x11 0x00 0x00
192 168 1 95
192 168 1 92
0xf2 0xc8 0x30 0x39 0x00 0x13 0x00 0x00
0x48 0x65 0x6c 0x6c 0x6f 0x20 0x57 0x6f 0x72 0x6c 0x64
)))
(unless (net-packet pkt)
(println (net-error))
(println (sys-error)))
net-peek
syntax: (net-peek int-socket)
(set sock (net-connect "example.com" 7306))
(while (= (net-peek sock) 0)
(do-something-else))
(net-receive sock buff 1024)
net-peer
syntax: (net-peer int-socket)
(net-peer sock)
;-> ("192.100.81.100" 13)
net-ping
syntax: (net-ping str-address [int-timeout [int-count bool]])
syntax: (net-ping list-addresses [int-timeout [int-count bool]])
(net-ping "localhost")
;-> (("127.0.0.1" 222))
(net-ping "example.com" 3000)
;-> ()
(net-ping '("example.com" "192.168.1.255") 2000 20)
;-> (("23.220.75.232" 826420) ("192.168.1.1" 124))
(net-ping "192.168.1.*" 500)
;-> (("192.168.1.1" 120) ("192.168.1.2" 245))
net-receive
syntax: (net-receive int-socket sym-buffer int-max-bytes [wait-string])
(net-receive sock buf 1024)
;-> 128
(define (net-receive-line sock buf)
(net-receive sock buf 256 "\n"))
(net-receive-line sock line)
;-> 42
net-receive-from
syntax: (net-receive-from int-socket int-max-size)
(set sock (net-listen 1001 "" "udp"))
;-> <socket>
(while (not (net-select sock "r" 100000))
(do-something))
(net-receive-from sock 20)
;-> ("hello" "192.168.0.5" 3240)
(net-send-to "192.168.0.5" 3240 "hello to you" sock)
(net-close sock)
net-receive-udp
syntax: (net-receive-udp int-port int-maxsize [int-microsec [str-addr-if]])
; wait for datagram (max 20 bytes)
(net-receive-udp 10001 20)
; wait with timeout (5 seconds)
(net-receive-udp 10001 20 5000000)
; sender
(net-send-udp "example.com" 10001 "Hello")
;-> 5
; receiver result
;-> ("Hello" "203.0.113.10" 3312)
; binary payload
(net-send-udp "example.com" 2222 (pack "c c c c" 0 1 2 3))
;-> 4
(set buf (first (net-receive-udp 2222 10)))
(unpack "c c c c" buf)
;-> (0 1 2 3)
net-select
syntax: (net-select int-socket str-mode int-micro-seconds)
syntax: (net-select list-sockets str-mode int-micro-seconds)
(set listen (net-listen 7306))
; wait for incoming connection
(while (not (net-select listen "r" 1000000))
(if (net-error) (print (net-error))))
(set conn (net-accept listen))
(net-send conn "hello")
; wait for incoming data
(while (not (net-select conn "r" 1000000))
(do-something))
(net-receive conn buf 1024)
(set listen-list '(1001 1002))
(while (not (net-error))
(dolist (s (net-select listen-list "r" 1000000))
(accept-connection s)))
net-send
syntax: (net-send int-socket str-buffer [int-num-bytes])
(set buf "hello there")
(net-send sock buf)
;-> 11
(net-send sock buf 5)
;-> 5
(net-send sock "bye bye")
;-> 7
net-send-to
syntax: (net-send-to str-remotehost int-remoteport str-buffer int-socket)
; UDP server
(set srv (net-listen 10001 "" "udp"))
(while (not (net-error))
(set msg (net-receive-from srv 255))
(net-send-to (nth 1 msg) (nth 2 msg)
(upper-case (first msg)) srv))
; UDP client
(set cli (net-listen 10002 "" "udp"))
(net-send-to "127.0.0.1" 10001 "hello" cli)
(net-receive cli buf 255)
net-send-udp
syntax: (net-send-udp str-remotehost int-remoteport str-buffer [bool])
(net-send-udp "example.com" 3333 "Hello")
;-> 5
(net-send-udp "192.168.1.255" 2000 "Hello" true)
;-> 5
net-service
syntax: (net-service str-service str-protocol)
syntax: (net-service int-port str-protocol)
(net-service "ftp" "tcp")
;-> 21
(net-service "http" "tcp")
;-> 80
(net-service 22 "tcp")
;-> "ssh"
net-sessions
syntax: (net-sessions)
(net-sessions)
;-> (3 4 7)
nil?
syntax: (nil? exp)
(map nil? '(x nil 1 nil "hi" ()))
;-> (nil true nil true nil nil)
(nil? nil)
;-> true
(nil? '())
;-> nil
; nil? means strictly nil
(nil? (not '()))
;-> nil
normal
syntax: (normal float-mean float-stdev int-n)
syntax: (normal float-mean float-stdev)
(normal 10 3 10)
;-> (7 6.563476562 11.93945312 6.153320312 9.98828125
;-> 7.984375 10.17871094 6.58984375 9.42578125
;-> 12.11230469)
(normal 1 0.2)
;-> 0.646875
not
syntax: (not exp)
(not true)
;-> nil
(not nil)
;-> true
(not '())
;-> true
(not (< 1 10))
;-> nil
(not (not (< 1 10)))
;-> true
now
syntax: (now [int-minutes-offset [int-index]])
(now)
;-> (2002 2 27 18 21 30 140000 57 3 -300 0)
(now 0 -2)
;-> -300
(date-value (now))
;-> 1765683697
index field
----- -------------------------------
0 year (Gregorian calendar)
1 month (1–12)
2 day (1–31)
3 hour (0–23, UTC)
4 minute (0–59)
5 second (0–59)
6 microsecond (0–999999)
7 day of year (Jan 1st is 1)
8 day of week (1–7, Monday = 1)
9 time zone offset (minutes west of GMT)
10 daylight savings time type
value meaning
----- -----------------------------------------
0 not on daylight savings
1 USA style DST
2 Australian style DST
3 Western European DST
4 Middle European DST
5 Eastern European DST
6 Canada DST
nper
syntax: (nper num-interest num-pmt num-pv [num-fv [int-type]])
(nper (div 0.07 12) 775.30 -100000)
;-> 239.9992828
npv
syntax: (npv num-interest list-values)
(npv 0.1 '(1000 1000 1000))
;-> 2486.851991
(npv 0.1 '(-2486.851991 1000 1000 1000))
;-> -1.434386832e-08
;-> ~ 0.0
nth
syntax: (nth int-index list)
syntax: (nth int-index array)
syntax: (nth int-index str)
syntax: (nth list-indices list)
syntax: (nth list-indices array)
(set lst '(a b c))
(nth 0 lst)
;-> a
; implicit indexing
(lst 0)
;-> a
(set names '(adam bela cyril david))
;-> (adam bela cyril david)
(nth 2 names)
;-> cyril
(names -1)
;-> david
(set people '((adam 30) (bela 42) ((cyril nova) 17)))
(people 1 1)
;-> 42
(nth '(2 0 1) people)
;-> nova
; implicit form
(people 2 0 1)
;-> nova
(set idx '(2 0 1))
(people idx)
;-> nova
(nth idx people)
;-> nova
(people -2 0)
;-> bela
(people 10)
;-> ERR: list index out of bounds
(people -5)
;-> ERR: list index out of bounds
(set L:L '(a b c d e f g))
(define (second ctx)
(nth 1 ctx))
(reverse L)
;-> (g f e d c b a)
L:L
;-> (g f e d c b a)
; by reference
(second L)
;-> b
; by value
(second L:L)
;-> b
(set arr (array 2 3 '(a b c d e f)))
;-> ((a b c) (d e f))
(nth 1 arr)
;-> (d e f)
(arr 1)
;-> (d e f)
(nth '(1 0) arr)
;-> d
(arr 1 0)
;-> d
(arr '(1 0))
;-> d
(nth 0 "Rebel")
;-> "R"
("Rebel" 0)
;-> "R"
("Rebel" -1)
;-> "l"
null?
syntax: (null? exp)
(set x (sqrt -1))
;-> -nan
(null? x)
;-> true
(map null? '(1 0 0.0 2 "hello" "" (a b c) () true))
;-> (nil true true nil nil true nil true nil)
(filter null? '(1 0 2 0.0 "hello" "" (a b c) () nil true))
;-> (0 0 "" () nil)
(clean null? '(1 0 2 0.0 "hello" "" (a b c) () nil true))
;-> (1 2 "hello" (a b c) true)
number?
syntax: (number? exp)
(set x 1.23)
(set y 456)
(number? x)
;-> true
(number? y)
;-> true
(number? "678")
;-> nil
odd?
syntax: (odd? int-number)
(odd? 123)
;-> true
(odd? 8)
;-> nil
(odd? 8.7)
;-> nil
open
syntax: (open str-path-file str-access-mode [str-option])
(device (open "file.txt" "write"))
;-> 5
(print "hello world\n")
;-> "hello world"
(close (device))
;-> 5
(set f (open "file.txt" "read"))
(seek f 6)
(set c (read-char f))
(print c "\n")
(close f)
or
syntax: (or exp-1 [exp-2 ... ])
(set x 10)
(or (> x 100) (= x 10))
;-> true
(or "hello" (> x 100) (= x 10))
;-> "hello"
(or '())
;-> ()
(or true)
;-> true
(or)
;-> nil
pack
syntax: (pack str-format [exp-1 [exp-2 ... ]])
syntax: (pack str-format [list])
syntax: (pack struct [exp-1 [exp-2 ... ]])
syntax: (pack struct [list])
code description
---- ----------------------------------------------
c signed 8-bit integer
b unsigned 8-bit integer
d signed 16-bit integer
u unsigned 16-bit integer
ld signed 32-bit integer
lu unsigned 32-bit integer
Ld signed 64-bit integer
Lu unsigned 64-bit integer
f 32-bit floating point number
lf 64-bit floating point number
sn string of n null-padded ASCII characters
nn n null bytes
> switch to big-endian byte order
< switch to little-endian byte order
(pack "c c c" 65 66 67)
;-> "ABC"
(unpack "c c c" "ABC")
;-> (65 66 67)
(pack "c c c" 0 1 2)
;-> "\000\001\002"
(unpack "c c c" "\000\001\002")
;-> (0 1 2)
(set s (pack "c d u" 10 12345 56789))
(unpack "c d u" s)
;-> (10 12345 56789)
(set s (pack "s10 f" "result" 1.23))
(unpack "s10 f" s)
;-> ("result\000\000\000\000" 1.230000019)
; Zero-filled formats:
;----------------------------------------------------------
(pack "n10")
;-> "\000\000\000\000\000\000\000\000\000\000"
(set lst '("A" "B" "C"))
(set buf (pack "lululu" lst))
(map get-string (unpack "lululu" buf))
;-> ("A" "B" "C")
; Byte order control:
;----------------------------------------------------------
(pack "d" 1)
;-> "\001\000"
(pack ">d" 1)
;-> "\000\001"
(pack ">u <u" 1 1)
;-> "\000\001\001\000"
(set txt "我能吞下玻璃而不伤身体。")
(set lst (unpack (dup "b" (length txt)) txt))
(pack (dup "b" (length lst)) lst)
;-> "我能吞下玻璃而不伤身体。"
parse
syntax: (parse str-data [str-break [regex-option]])
; no break string specified
(parse "hello how are you")
;-> ("hello" "how" "are" "you")
; implicit tokenization on spaces, punctuation, and numbers
(parse "weight is 10lbs")
;-> ("weight" "is" "10" "lbs")
; specifying a break string
(parse "one:two:three" ":")
;-> ("one" "two" "three")
(parse "one--two--three" "--")
;-> ("one" "two" "three")
; regular expression break patterns
(parse "one-two--three---four" "-+" 0)
;-> ("one" "two" "three" "four")
(parse "hello regular expression 1, 2, 3" {,\s*|\s+} 0)
;-> ("hello" "regular" "expression" "1" "2" "3")
; empty fields around separators are preserved
(parse "1,2,3," ",")
;-> ("1" "2" "3" "")
(parse "1,,,4" ",")
;-> ("1" "" "" "4")
(parse "," ",")
;-> ("" "")
; empty input always produces an empty list
(parse "")
;-> ()
(parse "" " ")
;-> ()
peek
syntax: (peek int-handle)
(peek 0)
;-> 12
pick
syntax: (pick exp-1 [exp-2 ...])
(pick 'a 'b 'c 'd 'e) ; → one of: a b c d e
(repeat (i 10)
(print (pick 3 5 7))) ; → 35777535755
pipe
syntax: (pipe)
(pipe)
;-> (3 4)
pmt
syntax: (pmt num-interest num-periods num-principal
[num-future-value [int-type]])
(pmt (div 0.07 12) 240 100000)
;-> -775.2989356
pop
syntax: (pop list [int-index-1 [int-index-2 ... ]])
syntax: (pop list [list-indexes])
syntax: (pop str [int-index [int-length]])
(set lst '((f g) a b c "hello" d e 10))
(pop lst)
;-> (f g)
(pop lst)
;-> a
lst
;-> (b c "hello" d e 10)
(pop lst 3)
;-> d
(pop lst -1)
;-> 10
lst
;-> (b c "hello" e)
(pop lst -1)
;-> e
lst
;-> (b c "hello")
(pop lst -2)
;-> c
lst
;-> (b "hello")
; nested indices
;----------------------------------------------------------
(set lst '(a 2 (x y (p q) z)))
(pop lst -1 2 0)
;-> p
; using indices in a list
;----------------------------------------------------------
(set lst '(a b (c d () e)))
(push 'x lst '(2 2 0))
;-> (a b (c d (x) e))
lst
;-> (a b (c d (x) e))
(ref 'x lst)
;-> (2 2 0)
(pop lst '(2 2 0))
;-> x
; pop on strings (UTF-8 aware)
;----------------------------------------------------------
(set str "Rebel")
(pop str -2 2)
;-> "el"
str
;-> "Reb"
(pop str 1)
;-> "e"
str
;-> "Rb"
(set str "x")
(pop str)
;-> "x"
(pop str)
;-> ""
pop-assoc
syntax: (pop-assoc exp-key list-assoc)
syntax: (pop-assoc list-keys list-assoc)
; simple associations
(set lst '((a 1) (b 2) (c 3)))
(pop-assoc 'b lst)
;-> (b 2)
lst
;-> ((a 1) (c 3))
;----------------------------------------------------------
; nested associations
(set lst '((a (b 1) (c (d 2)))))
(pop-assoc 'a lst)
;-> (a (b 1) (c (d 2)))
lst
;-> ()
(set lst '((a (b 1) (c (d 2)))))
(pop-assoc '(a b) lst)
;-> (b 1)
lst
;-> ((a (c (d 2))))
(set lst '((a (b 1) (c (d 2)))))
(pop-assoc '(a c) lst)
;-> (c (d 2))
lst
;-> ((a (b 1)))
post-url
syntax: (post-url str-url str-content [str-content-type [str-option] [int-timeout [str-header]]])
application/x-www-form-urlencoded
; specify content type
(post-url "https://example.com/form.cgi"
"name=johnDoe&city=New%20York"
"application/x-www-form-urlencoded")
; specify content type and timeout
(post-url "https://example.com/form.cgi"
"name=johnDoe&city=New%20York"
"application/x-www-form-urlencoded"
nil
8000)
; default content type, no timeout
(post-url "https://example.com/form.rbl"
"name=johnDoe&city=New%20York")
pow
syntax: (pow num-1 num-2 [num-3 ... ])
syntax: (pow num-1)
(pow 100 2)
;-> 10000
(pow 100 0.5)
;-> 10
(pow 100 0.5 3)
;-> 1000
(pow 3)
;-> 9
prefix
syntax: (prefix sym)
(setf s 'ctx:var)
;-> ctx:var
(prefix s)
;-> ctx
(context? (prefix s))
;-> true
(term s)
;-> "var"
(= s (sym (term s) (prefix s)))
;-> true
(context (prefix s))
;-> ctx
prefix
syntax: (prefix sym)
(setf s 'ctx:var)
;-> ctx:var
(prefix s)
;-> ctx
(context? (prefix s))
;-> true
(term s)
;-> "var"
(= s (sym (term s) (prefix s)))
;-> true
(context (prefix s))
;-> ctx
pretty-print
syntax: (pretty-print [int-length [str-tab [str-fp-format]]])
(pretty-print)
;-> (80 " " "%1.15g")
(pretty-print 90 "\t")
;-> (90 "\t" "%1.15g")
(pretty-print 100)
;-> (100 "\t" "%1.15g")
(sin 1)
;-> 0.841470984807897
(pretty-print 80 " " "%1.3f")
(sin 1)
;-> 0.841
(set x 0.0)
x
;-> 0.000
(print (string my-expression))
primitive?
syntax: (primitive? exp)
(set var define)
(primitive? var)
;-> true
print
syntax: (print exp-1 [exp-2 ... ])
code description
----- -----------------------------------------
\n line feed (ASCII 10)
\r carriage return (ASCII 13)
\t tab character (ASCII 9)
\nnn decimal ASCII code (000–255)
\xnn hexadecimal ASCII code (00–FF)
(print (set res (+ 1 2 3)))
(print "the result is " res "\n")
"\065\066\067"
;-> "ABC"
println
syntax: (println exp-1 [exp-2 ... ])
(println "hello world")
;-> "hello world\n"
(println "the result is " (+ 1 2 3))
;-> "the result is 6\n"
prob-chi2
syntax: (prob-chi2 num-chi2 int-df)
(prob-chi2 10 6)
;-> 0.1246520195
prob-f
syntax: (prob-f num-f int-df1 int-df2)
(prob-f 2.75 10 12)
;-> 0.0501990804
prob-t
syntax: (prob-t num-t int-df)
(prob-t 1.76 14)
;-> 0.05011454551
prob-z
syntax: (prob-z num-z)
(prob-z 0.0)
;-> 0.5
process
syntax: (process str-command)
syntax: (process str-command int-pipe-in int-pipe-out)
syntax: (process str-command int-pipe-in int-pipe-out int-pipe-error)
(process "/usr/bin/true")
;-> 12345
(map with '(in out) (pipe))
(map with '(cin cout) (pipe))
(process "/usr/bin/bc" cin out)
;-> 7916
(write-line cout "3 + 4")
(read-line in)
;-> "7"
(destroy 7916)
(map with '(in out) (pipe))
(map with '(cin cout) (pipe))
(map with '(errin errout) (pipe))
(process "/usr/bin/bc" cin out errout)
(write-line cout "invalid")
(while (and (= (peek in) 0)
(= (peek errin) 0))
(sleep 10))
(if (> (peek errin) 0)
(println (read-line errin)))
(if (> (peek in) 0)
(println (read-line in)))
(process "app" 0 appout)
prompt-event
syntax: (prompt-event sym-event-handler | func-event-handler)
syntax: (prompt-event nil)
(prompt-event (fn (ctx)
(string ctx ":" (real-path) "$ ")))
protected?
syntax: (protected? sym)
(protected? 'println)
;-> true
(constant 'var 123)
(protected? 'var)
;-> true
push
syntax: (push exp list [int-index-1 [int-index-2 ... ]])
syntax: (push exp list [list-indexes])
syntax: (push str-1 str-2 [int-index])
; inserting at the front
(set lst '(b c))
(push 'a lst)
;-> (a b c)
lst
;-> (a b c)
; insert at index
(push "hello" lst 2)
;-> (a b "hello" c)
; optimized appending at the end
(push 'z lst -1)
;-> (a b "hello" c z)
; inserting lists into lists
(push '(f g) lst)
;-> ((f g) a b "hello" c z)
; inserting at a negative index
(push 'x lst -3)
;-> ((f g) a b "hello" x c z)
; using multiple indices
(push 'h lst 0 -1)
;-> ((f g h) a b "hello" x c z)
; using indices in a list
;----------------------------------------------------------
(set lst '(a b (c d () e)))
(push 'x lst '(2 2 0))
;-> (a b (c d (x) e))
(ref 'x lst)
;-> (2 2 0)
(pop lst '(2 2 0))
;-> x
; place reference
;----------------------------------------------------------
(set lst '((a 1) (b 2) (c 3) (d)))
(push 4 (assoc 'd lst) -1)
;-> (d 4)
lst
;-> ((a 1) (b 2) (c 3) (d 4))
; push on uninitialized symbol
;----------------------------------------------------------
(var)
;-> nil
(push 999 var)
;-> (999)
var
;-> (999)
; using push and pop as a queue
;----------------------------------------------------------
(set q '(a b c d e))
(pop (push 'f q -1))
;-> a
(pop (push 'g q -1))
;-> b
q
;-> (c d e f g)
; push on strings (UTF-8 aware)
;----------------------------------------------------------
(set str "abcdefg")
(push "hijk" str -1)
;-> "abcdefghijk"
str
;-> "abcdefghijk"
(push "123" str)
;-> "123abcdefghijk"
(push "4" str 3)
;-> "1234abcdefghijk"
(set str "\u03b1\u03b2\u03b3")
;-> "αβγ"
(push "*" str 1)
;-> "α*βγ"
; push on a string reference
;----------------------------------------------------------
(set lst '("abc" "xyz"))
(push "x" (lst 0))
;-> "xabc"
lst
;-> ("xabc" "xyz")
put-url
syntax: (put-url str-url str-content [str-option] [int-timeout [str-header]])
; upload text to a remote resource
(put-url "https://example.com/data.txt" "Hello world")
; upload text with timeout
(put-url "https://example.com/data.txt" "Hello world" nil 2000)
; upload file contents
(put-url "https://example.com/page.html"
(read-file "page.html"))
; write to local file system
(put-url "file:///home/user/file.txt" "Hello world")
pv
syntax: (pv num-int num-nper num-pmt [num-fv [int-type]])
(pv (div 0.07 12) 240 775.30)
;-> -100000.1373
quote
syntax: (quote exp)
(quote x)
;-> x
(quote 123)
;-> 123
(quote (a b c))
;-> (a b c)
(= (quote x) 'x)
;-> true
rand
syntax: (rand int-range [int-N])
(repeat (x 100)
(print (rand 2)))
;-> 11100000110100111100111101...
(rand 3 100)
;-> (2 0 1 1 2 0 ...)
random
syntax: (random float-offset float-scale int-n)
syntax: (random float-offset float-scale)
(random 0 1 10)
;-> (0.10898973 0.69823783 0.56434872 0.041507289 0.16516733
; 0.81540917 0.68553784 0.76471068 0.82314585 0.95924564)
(random 10 5)
;-> 11.0971
randomize
syntax: (randomize list [bool])
(randomize '(a b c d e f g))
;-> (b a c g d e f)
(randomize (sequence 1 5))
;-> (3 5 4 1 2)
(randomize '(a b c d) true)
;-> (a b c d)
read
syntax: (read int-file sym-buffer int-size [str-wait])
(set handle (open "file.txt" "read"))
(read handle buf 200)
;-> 200
buf
;-> "..."
(read handle buf 1000 "password:")
;-> 143
buf
;-> "...password:"
read-char
syntax: (read-char [int-file])
(define (copy-bytes from-file to-file)
(set in-file (open from-file "read"))
(set out-file (open to-file "write"))
(while (set chr (read-char in-file))
(write-char out-file chr))
(close in-file)
(close out-file)
"finished")
read-expr
syntax: (read-expr str-source [sym-context [exp-error [int-offset]]])
(set code "; a statement
(define (double x) (+ x x))")
(read-expr code)
;-> (define (double x) (+ x x))
$count
;-> 41
(read-expr "(+ 3 4)")
;-> (+ 3 4)
(eval-string "(+ 3 4)")
;-> 7
read-file
syntax: (read-file str-file-name)
(write-file "file.enc"
(encrypt (read-file "file.txt") "secret"))
(read-file "http://example.com/file.tgz" 10000)
read-key
syntax: (read-key [true])
(read-key)
;-> 97 ; after pressing the A key
(read-key)
;-> 65 ; after pressing shifted A
(read-key true)
;-> 0 ; when no key has been pressed
(while (!= (set c (read-key)) 1)
(println c))
read-line
syntax: (read-line [int-file])
(print "Enter a num:")
(set num (int (read-line)))
(set in-file (open "file.txt" "read"))
(while (read-line in-file)
(write-line))
(close in-file)
read-utf8
syntax: (read-utf8 int-file)
(set in-file (open "utf8.txt" "read"))
(while (set chr (read-utf8 in-file))
(print (char chr)))
(close in-file)
reader-event
syntax: (reader-event [sym-event-handler | func-event-handler])
syntax: (reader-event nil)
(reader-event (fn (ex)
(print " => " ex)
ex))
(+ 1 2 3)
; prints: => (+ 1 2 3)
;-> 6
real-path
syntax: (real-path [str-path])
syntax: (real-path str-exec-name true)
(real-path)
;-> "/home/user"
(real-path "./file.txt")
;-> "/home/user/file.txt"
(real-path "make" true)
;-> "/usr/bin/make"
receive
syntax: (receive int-pid sym-message)
syntax: (receive)
; sending process
(send spid "hello")
;-> true
; receiving process
(receive pid msg)
;-> true
msg
;-> "hello"
(until (receive pid msg))
(dolist (pid (receive))
(receive pid msg)
(println "received message: " msg " from:" pid))
ref
syntax: (ref exp-key list [func-compare [true]])
(set lst '(a b (c d (x) e)))
(ref 'x lst)
;-> (2 2 0)
(ref '(x) lst)
;-> (2 2)
(set p '(c d (x) e))
(ref p lst)
;-> (2)
(set v (ref '(x) lst))
(lst v)
;-> (x)
(ref 'foo lst)
;-> nil
(set lst '(a b (c d (e) f)))
(ref 'e lst)
;-> (2 2 0)
(ref 'e lst =)
;-> (2 2 0)
(ref 'e lst >)
;-> (0)
(ref 'e lst > true)
;-> a
(ref 'e lst (fn (x y) (or (= x y) (= y 'd))))
;-> (2 1)
(ref 'e lst (fn (x y) (or (= x y) (= y 'd))) true)
;-> d
(set lst '((l 3) (a 12) (k 5) (a 10) (z 22)))
(ref '(a ?) lst match)
;-> (1)
(set lst '(((a b) (c d)) ((e e) (f g))))
(ref '(X X) lst unify)
;-> (1 0)
(ref '(X g) lst unify)
;-> (1 1)
(ref '(X g) lst unify true)
;-> (f g)
(set ctx:ctx '(a b (c d) e f))
(ref 'd ctx)
;-> (2 1)
ref-all
syntax: (ref-all exp-key list [func-compare [true]])
; basic usage
;----------------------------------------------------------
(set lst '(a b c (d a f (a h a)) (k a (m n a) (x))))
(ref-all 'a lst)
;-> ((0) (3 1) (3 3 0) (3 3 2) (4 1) (4 2 2))
$count
;-> 6
(lst '(3 1))
;-> a
(map 'lst (ref-all 'a lst))
;-> (a a a a a a)
; comparison functions
;----------------------------------------------------------
(set lst '(a b c (d f (h l a)) (k a (m n) (x))))
(ref-all 'c lst)
;-> ((2))
(ref-all 'c lst =)
;-> ((2))
(ref-all 'c lst >)
;-> ((0) (1) (3 2 2) (4 1))
(ref-all 'c lst > true)
;-> (a b a a)
; Using an anonymous comparison function:
;----------------------------------------------------------
(ref-all 'a lst (fn (x y) (or (= x y) (= y 'k))))
;-> ((0) (3 2 2) (4 0) (4 1))
; comparison ignoring the key
;----------------------------------------------------------
(ref-all nil lst (fn (x y) (> (length y) 2)))
;-> ((3) (3 2) (4))
; named comparison functions
;----------------------------------------------------------
(define (is-long? x y)
(> (length y) 2))
(ref-all nil lst is-long?)
;-> ((3) (3 2) (4))
(define (is-it-or-d x y)
(or (= x y) (= y 'd)))
(set lst '(a b (c d (e) f)))
(ref-all 'e lst is-it-or-d)
;-> ((2 1) (2 2 0))
; using match and unify
;----------------------------------------------------------
(set lst '((l 3) (a 12) (k 5) (a 10) (z 22)))
(ref-all '(a ?) lst match)
;-> ((1) (3))
(ref-all '(a ?) lst match true)
;-> ((a 12) (a 10))
(set lst '(((a b) (c d)) ((e e) (f g)) ((z) (z))))
(ref-all '(X X) lst unify)
;-> ((1 0) (2))
(ref-all '(X X) lst unify true)
;-> ((e e) ((z) (z)))
(set lst '(((x y z) g) ((a b) (c d)) ((e e) (f g))))
(ref-all '(X g) lst unify)
;-> ((0) (2 1))
(ref-all '(X g) lst unify true)
;-> (((x y z) g) (f g))
regex
syntax: (regex str-pattern str-text [regex-option [int-offset]])
; basic matching
;----------------------------------------------------------
(regex "b+" "aaaabbbaaaa")
;-> ("bbb" 4 3)
(regex "b+" "AAAABBBAAAA" 1)
;-> ("BBB" 4 3)
(regex "b+" "AAAABBBAAAA" "i")
;-> ("BBB" 4 3)
(regex "[bB]+" "AAAABbBAAAA")
;-> ("BbB" 4 3)
; subexpressions
;----------------------------------------------------------
(regex "http://(.*):(.*)" "http://example.com:80")
;-> ("http://example.com:80" 0 22 "example.com" 7 11 "80" 19 2)
$0
;-> "http://example.com:80"
$1
;-> "example.com"
$2
;-> "80"
; escaping rules
;----------------------------------------------------------
(regex "\\(abc\\)" "xyz(abc)xyz")
;-> ("(abc)" 3 5)
(regex "\\d{1,3}" "qwerty567asdfg")
;-> ("567" 6 3)
(regex "\"" "abc\"def")
;-> ("\"" 3 1)
(regex {\(abc\)} "xyz(abc)xyz")
;-> ("(abc)" 3 5)
(regex {"} "abc\"def")
;-> ("\"" 3 1)
(regex [text]\(abc\)[/text] "xyz(abc)xyz")
;-> ("(abc)" 3 5)
; balanced brackets
;----------------------------------------------------------
(regex {\d{1,3}} "qwerty567asdfg")
;-> ("567" 6 3)
no letter description
-------- -------- -----------------------------------------
1 i case-insensitive matching
2 m multiline mode
4 s dot matches newline
8 x ignore whitespace in pattern
16 A anchor at start of string
32 D $ matches end of string only
64 extra functionality (unused)
128 ^ does not match start of string
256 $ does not match end of string
512 U ungreedy quantifiers
1024 empty string considered invalid
2048 u UTF-8 mode
0x8000 replace once (replace only)
0x10000 p precompiled pattern
regex-comp
syntax: (regex-comp str-pattern [int-option])
; slower without pre-compilation
;----------------------------------------------------------
(dolist (line page)
(replace pattern-str1 line repl1 0)
(replace pattern-str2 line repl2 512))
; faster with pre-compilation
;----------------------------------------------------------
(set p1 (regex-comp pattern-str1))
(set p2 (regex-comp pattern-str2 512))
(dolist (line page)
(replace p1 line repl1 0x10000)
(replace p2 line repl2 0x10000))
remove-dir
syntax: (remove-dir str-path)
(remove-dir "tmp")
;-> true
rename-file
syntax: (rename-file str-path-old str-path-new)
(rename-file "data.txt" "data.backup")
;-> true
repeat
syntax: (repeat (sym-var int-count [exp-break]) body)
sym-var is bound to the current loop index, starting at 0
and ending at int-count - 1. The binding is local to the
loop and follows dynamic scoping rules. The return value
is the last evaluation of body.exp-break is present, it is evaluated before each
iteration step. When exp-break evaluates to a non-nil
value, the loop terminates immediately and returns that
value.repeat finishes, sym-var reverts to its previous
value.(repeat (i 10)
(print i))
;-> 9
; console output:
; 0123456789
; early exit example:
(repeat (i 10 (= i 3))
(print i))
;-> true
; console output:
; 012
sym-var is always an integer.exp-break is checked before body is evaluated.exp-break on early termination.
replace
syntax: (replace exp-key list exp-replacement [func-compare])
syntax: (replace exp-key list)
syntax: (replace str-key str-data exp-replacement)
syntax: (replace str-pattern str-data exp-replacement regex-option)
; list replacement
;----------------------------------------------------------
(set lst '(a b c d e a b c d))
(replace 'b lst 'B)
;-> (a B c d e a B c d)
lst
;-> (a B c d e a B c d)
$count
;-> 2
; list replacement with comparison function
;----------------------------------------------------------
(set lst '(1 4 22 5 6 89 2 3 24))
(replace 10 lst 10 <)
;-> (1 4 10 5 6 10 2 3 10)
$count
;-> 3
(replace 10 lst 10 (fn (x y) (< x y)))
;-> (1 4 10 5 6 10 2 3 10)
; dynamic replacement using $it and $count
;----------------------------------------------------------
(replace 'a '(a b a b a b) (list $count $it) =)
;-> ((1 a) b (2 a) b (3 a) b)
; using match and unify on lists
;----------------------------------------------------------
(set lst '((john 5 6 4) (mary 3 4 7) (bob 4 2 7 9) (jane 3)))
(replace '(mary *) lst
(list 'mary (apply + (rest $it)))
match)
;-> ((john 5 6 4) (mary 14) (bob 4 2 7 9) (jane 3))
(set lst '((john 5 6 4) (mary 3 4 7) (bob 4 2 7 9) (jane 3)))
(replace '(*) lst
(list ($it 0) (apply + (rest $it)))
match)
;-> ((john 15) (mary 14) (bob 22) (jane 3))
(replace '(X X)
'((3 10) (2 5) (4 4) (6 7) (8 8))
(list ($it 0) 'double ($it 1))
unify)
;-> ((3 10) (2 5) (4 double 4) (6 7) (8 double 8))
; list removal
;----------------------------------------------------------
(set lst '(a b a a c d a f g))
(replace 'a lst)
;-> (b c d f g)
lst
;-> (b c d f g)
$count
;-> 4
; string replacement without regex
;----------------------------------------------------------
(set str "this isa sentence")
(replace "isa" str "is a")
;-> "this is a sentence"
$count
;-> 1
; regular expression replacement
;----------------------------------------------------------
(set str "ZZZZZxZZZZyy")
(replace "x|y" str "PP" 0)
;-> "ZZZZZPPZZZZPPPP"
(set str "---axb---ayb---")
(replace "(a)(.)(b)" str (append $3 $2 $1) 0)
;-> "---bxa---bya---"
(replace "a" "aaa" "X" 0)
;-> "XXX"
(replace "a" "aaa" "X" 0x8000)
;-> "Xaa"
; dynamic regex replacement
;----------------------------------------------------------
(set str "xxx%41xxx%42")
(replace "%([0-9A-F][0-9A-F])" str
(char (int (append "0x" $1)))
1)
str
;-> "xxxAxxxB"
$count
;-> 2
reset
syntax: (reset)
syntax: (reset true)
syntax: (reset int-max-cells)
(sys-info)
;-> (437 576460752303423488 409 1 0 2048 0 60391 10602 1411)
; allocate approximately 1 MB of cell memory
(reset 32768)
;-> true
(sys-info)
;-> (437 32768 409 1 0 2048 0 60392 10602 1411)
rest
syntax: (rest list)
syntax: (rest array)
syntax: (rest str)
; list usage
;----------------------------------------------------------
(rest '(1 2 3 4))
;-> (2 3 4)
(rest '((a b) c d))
;-> (c d)
(set lst '(a b c d e))
(rest lst)
;-> (b c d e)
(first (rest lst))
;-> b
(rest (rest lst))
;-> (d e)
(rest (first '((a b) c d)))
;-> (b)
(rest '())
;-> ()
; array usage
;----------------------------------------------------------
(set A (array 2 3 (sequence 1 6)))
;-> ((1 2) (3 4) (5 6))
(rest A)
;-> ((3 4) (5 6))
; string usage
;----------------------------------------------------------
(rest "Rebel")
;-> "ebel"
(first (rest "Rebel"))
;-> "e"
reverse
syntax: (reverse list)
syntax: (reverse array)
syntax: (reverse str)
; reverse a list
;----------------------------------------------------------
(set lst '(a b c d e f))
(reverse lst)
;-> (f e d c b a)
lst
;-> (f e d c b a)
; reverse an array
;----------------------------------------------------------
(set arr (array 3 2 '(1 2 3 4 5 6)))
;-> ((1 2) (3 4) (5 6))
(reverse arr)
;-> ((5 6) (3 4) (1 2))
arr
;-> ((5 6) (3 4) (1 2))
; reverse a byte string
;----------------------------------------------------------
(set str "Rebel")
(reverse str)
;-> "lebeR"
str
;-> "lebeR"
; reverse a UTF-8 string
;----------------------------------------------------------
(join (reverse (explode "ΑΒΓΔΕΖΗΘ")))
;-> "ΘΗΖΕΔΓΒΑ"
rotate
syntax: (rotate list [int-count])
syntax: (rotate str [int-count])
; list rotation
;----------------------------------------------------------
(set lst '(1 2 3 4 5 6 7 8 9))
(rotate lst)
;-> (9 1 2 3 4 5 6 7 8)
(rotate lst 2)
;-> (7 8 9 1 2 3 4 5 6)
lst
;-> (7 8 9 1 2 3 4 5 6)
(rotate lst -3)
;-> (1 2 3 4 5 6 7 8 9)
; string rotation (byte-based)
;----------------------------------------------------------
(set str "Rebel")
(rotate str)
;-> "lRebe"
(rotate str 2)
;-> "elReb"
(rotate str -2)
;-> "Rebel"
; UTF-8 character rotation using explode
;----------------------------------------------------------
(join (rotate (explode "ΑΒΓΔΕΖΗΘ")))
;-> "ΘΑΒΓΔΕΖΗ"
round
syntax: (round number [int-digits])
; integer rounding
;----------------------------------------------------------
(round 123.49 2)
;-> 100
(round 123.49 1)
;-> 120
(round 123.49 0)
;-> 123
(round 123.49)
;-> 123
; decimal rounding
;----------------------------------------------------------
(round 123.49 -1)
;-> 123.5
(round 123.49 -2)
;-> 123.49
save
syntax: (save str-file)
syntax: (save str-file sym-1 [sym-2 ... ])
; save entire workspace
;----------------------------------------------------------
(save "workspace.txt")
;-> true
; save a single function
;----------------------------------------------------------
(save "fn.txt" 'fn)
; save a context
;----------------------------------------------------------
(save "ctx.txt" 'ctx:ctx)
; save multiple symbols and contexts
;----------------------------------------------------------
(save "stuff.txt" 'ctx:ctx 'fn '$main-args)
; save to a remote location (HTTP PUT)
;----------------------------------------------------------
(save "http://example.com/source.txt" 'fn)
search
syntax: (search int-file str-search [bool-flag [regex-option]])
; plain string search
;----------------------------------------------------------
(set file (open "file.txt" "read"))
(search file "define")
(print (read-line file) "\n")
(close file)
; regular expression search
;----------------------------------------------------------
(set file (open "program.c" "read"))
(while (search file "#define (.*)" true 0)
(println $1))
(close file)
seed
syntax: (seed int-seed)
syntax: (seed int-seed true [int-pre-N])
syntax: (seed)
(seed 12345)
;-> 12345
(seed (time-of-day))
;-> int
; deterministic generator with reproducible sequence
;------------------------------------------------------------
(seed 123 true)
;-> 123
(random)
;-> 0.2788576787704871
(random)
;-> 0.7610070955758016
(random)
;-> 0.2462553424976092
(random)
;-> 0.8135413573186572
; save current generator state
(set state (seed))
;-> int
(random)
;-> 0.1895924546707387
(random)
;-> 0.4803856511043318
; restore previous generator state
(seed state true 0)
;-> int
(random)
;-> 0.1895924546707387
(random)
;-> 0.4803856511043318
self
syntax: (self [int-index ... ])
(new Class 'Circle)
(define (Circle:move dx dy)
(inc (self 1) dx)
(inc (self 2) dy))
(set Circle1 (Circle 1 2 3))
(:move Circle1 10 20)
Circle1
;-> (Circle 11 22 3)
; objects can be anonymous
;------------------------------------------------------------
(set circles '((Circle 1 2 3) (Circle 4 5 6)))
(:move (circles 0) 10 20)
(:move (circles 1) 10 20)
circles
;-> ((Circle 11 22 3) (Circle 14 25 6))
seek
syntax: (seek int-file [int-position])
(set file (open "file.dat" "read"))
;-> int
(seek file 100)
;-> 100
(seek file)
;-> 100
(seek file -1) ; seek to end of file
;-> int
(set big (open "large-file" "read"))
(seek big 30000000000)
;-> 30000000000
select [utf8]
syntax: (select list list-selection)
syntax: (select list [int-index_i ... ])
syntax: (select string list-selection)
syntax: (select string [int-index_i ... ])
; list selection
;------------------------------------------------------------
(set lst '(a b c d e f g))
(select lst '(0 3 2 5 3))
;-> (a d c f d)
(select lst '(-2 -1 0))
;-> (f g a)
(select lst -2 -1 0)
;-> (f g a)
; string selection (UTF-8 aware)
;------------------------------------------------------------
(set str "abcdefg")
(select str '(0 3 2 5 3))
;-> "adcfd"
(select str '(-2 -1 0))
;-> "fga"
(select str -2 -1 0)
;-> "fga"
semaphore
syntax: (semaphore)
syntax: (semaphore int-id)
syntax: (semaphore int-id int-wait)
syntax: (semaphore int-id int-signal)
syntax: (semaphore int-id 0)
; create semaphore
;------------------------------------------------------------
(set sid (semaphore))
;-> int
(semaphore sid)
;-> 0
; wait (block until signaled)
;------------------------------------------------------------
(semaphore sid -1)
; signal once
;------------------------------------------------------------
(semaphore sid 1)
; signal multiple times
;------------------------------------------------------------
(semaphore sid 3)
; release semaphore
;------------------------------------------------------------
(semaphore sid 0)
(define (counter n)
(println "counter started")
(repeat (x n)
(semaphore sid -1)
(println x)))
(set sid (semaphore))
(fork (counter 5))
(semaphore sid 1)
(semaphore sid 3)
(semaphore sid 1)
send
syntax: (send int-pid exp)
syntax: (send)
; child sending message to parent
;------------------------------------------------------------
(set ppid (sys-info -4))
(send ppid "hello")
; parent receiving message
;------------------------------------------------------------
(receive child-pid msg)
msg
;-> "hello"
; blocking send and receive
;------------------------------------------------------------
(until (send pid msg))
(until (receive pid msg))
; parent dispatching messages from multiple children
;------------------------------------------------------------
(define (child)
(set ppid (sys-info -4))
(while true
(until (send ppid (rand 100)))))
(repeat (i 5)
(spawn 'result (child) true))
(for (i 1 3)
(dolist (cpid (sync))
(until (receive cpid msg))
(print "pid:" cpid "->" msg " "))
(println))
sequence
syntax: (sequence num-start num-end [num-step])
(sequence 10 5)
;-> (10 9 8 7 6 5)
(sequence 0 1 0.2)
;-> (0 0.2 0.4 0.6 0.8 1)
(sequence 2 0 0.3)
;-> (2 1.7 1.4 1.1 0.8 0.5 0.2)
series
syntax: (series num-start num-factor num-count)
syntax: (series exp-start function num-count)
; geometric sequences
;------------------------------------------------------------
(series 2 2 5)
;-> (2 4 8 16 32)
(series 1 1.2 6)
;-> (1 1.2 1.44 1.728 2.0736 2.48832)
(series 10 0.9 4)
;-> (10 9 8.1 7.29)
(series 0 0 10)
;-> (0 0 0 0 0 0 0 0 0 0)
(series 99 1 5)
;-> (99 99 99 99 99)
; functional series
;------------------------------------------------------------
(series 1 (fn (x) (div (add 1 x))) 20)
;-> (1 0.5 0.6666666 0.6 0.625 0.6153846 0.619047 0.6176470
; 0.6181818 0.6179775 0.6180555 0.6180257 0.6180371
; 0.6180327 0.6180344 0.6180338 0.6180340 0.6180339
; 0.6180339 0.6180339)
(define (oscillate x)
(if (< x)
(+ (- x) 1)
(- (+ x 1))))
(series 1 oscillate 20)
;-> (1 -2 3 -4 5 -6 7 -8 9 -10 11 -12 13 -14 15 -16 17 -18
; 19 -20)
; non-numeric data
;------------------------------------------------------------
(series "a" (fn (c) (char (inc (char c)))) 5)
;-> ("a" "b" "c" "d" "e")
; dependency on previous values
;------------------------------------------------------------
(let (x 1)
(series x (fn (y) (+ x (swap y x))) 10))
;-> (1 2 3 5 8 13 21 34 55 89)
set
syntax: (set sym-1 exp-1 [sym-2 exp-2 ... ])
; basic assignment
;------------------------------------------------------------
(set x 123)
;-> 123
(set x 'y)
;-> y
(set x "hello")
;-> "hello"
y
;-> "hello"
(set lst '(1 2 3))
;-> (1 2 3)
; multiple assignments
;------------------------------------------------------------
(set x 1 'y "hello")
;-> "hello"
x
;-> 1
y
;-> "hello"
; symbol computed by expression
;------------------------------------------------------------
(set lst '(x y z))
;-> (x y z)
(set (first lst) 123)
;-> 123
x
;-> 123
; expressions may depend on earlier assignments
;------------------------------------------------------------
(set a 10 'b (+ a a))
a
;-> 10
b
;-> 20
; assigning functions
;------------------------------------------------------------
(set double (fn (x) (+ x x)))
;-> (fn (x) (+ x x))
; equivalent to define
(define (double x) (+ x x))
;-> (fn (x) (+ x x))
set-locale
syntax: (set-locale [str-locale [int-category]])
; report current locale
;------------------------------------------------------------
(set-locale)
;-> ("C" ".")
; set system default locale
;------------------------------------------------------------
(set-locale "")
;-> (str-locale str-decimal)
; change numeric formatting only (decimal separator)
;------------------------------------------------------------
(set-locale "de_DE.UTF-8" 4)
;-> ("de_DE.UTF-8" ",")
LC_ALL 0
LC_COLLATE 1
LC_CTYPE 2
LC_MONETARY 3
LC_NUMERIC 4
LC_TIME 5
set-ref
syntax: (set-ref exp-key list exp-replacement [func-compare])
; simple replacement in nested list
;------------------------------------------------------------
(set data '(fruits (apples 123 44) (oranges 1 5 3)))
(set-ref 'apples data 'Apples)
;-> (fruits (Apples 123 44) (oranges 1 5 3))
data
;-> (fruits (Apples 123 44) (oranges 1 5 3))
; passing list by reference via context
;------------------------------------------------------------
(set db:db '(fruits (apples 123 44) (oranges 1 5 3)))
(define (update ct key value)
(set-ref key ct value))
(update db 'apples 'Apples)
;-> (fruits (Apples 123 44) (oranges 1 5 3))
(update db 'oranges 'Oranges)
;-> (fruits (Apples 123 44) (Oranges 1 5 3))
db:db
;-> (fruits (Apples 123 44) (Oranges 1 5 3))
set-ref-all
syntax: (set-ref-all exp-key list exp-replacement [func-compare])
; replace all matching elements
;------------------------------------------------------------
(set data
'((monday (apples 20 30) (oranges 2 4 9))
(tuesday (apples 5) (oranges 32 1))))
(set-ref-all 'apples data "Apples")
;-> ((monday ("Apples" 20 30) (oranges 2 4 9))
; (tuesday ("Apples" 5) (oranges 32 1)))
$count
;-> 2
; passing list by reference via context
;------------------------------------------------------------
(set db:db
'((monday (apples 20 30) (oranges 2 4 9))
(tuesday (apples 5) (oranges 32 1))))
(define (foo ctx)
(set-ref-all 'apples ctx "Apples"))
(foo db)
;-> ((monday ("Apples" 20 30) (oranges 2 4 9))
; (tuesday ("Apples" 5) (oranges 32 1)))
db:db
;-> ((monday ("Apples" 20 30) (oranges 2 4 9))
; (tuesday ("Apples" 5) (oranges 32 1)))
; custom comparison using match
;------------------------------------------------------------
(set data
'((monday (apples 20 30) (oranges 2 4 9))
(tuesday (apples 5) (oranges 32 1))))
(set-ref-all '(oranges *) data
(list (first $it) (apply + (rest $it)))
match)
;-> (... (oranges 15) ... (oranges 33) ...)
setq, setf
syntax: (setq place-1 exp-1 [place-2 exp-2 ... ])
syntax: (setf place-1 exp-1 [place-2 exp-2 ... ])
; symbol assignment
;------------------------------------------------------------
(setq x 123)
;-> 123
(setq x 1 y 2 z 3)
;-> 3
x
;-> 1
y
;-> 2
z
;-> 3
; list assignment using implicit indices
;------------------------------------------------------------
(setq lst '(a b (c d) e f g))
(setf (lst 1) 'B)
;-> B
lst
;-> (a B (c d) e f g)
(setf (nth 1 lst) 'B)
;-> B
(setf (lst 2 0) 'C)
;-> C
lst
;-> (a B (C d) e f g)
(setf (lst 2) 'X)
;-> X
lst
;-> (a B X e f g)
; assignment using assoc
;------------------------------------------------------------
(setq lst '((a 1) (b 2)))
(setf (assoc 'b lst) '(b 3))
;-> (b 3)
lst
;-> ((a 1) (b 3))
; assignment using lookup
;------------------------------------------------------------
(setf (lookup 'b lst) 30)
;-> 30
lst
;-> ((a 1) (b 30))
; nested accessors
;------------------------------------------------------------
(setq lst '((a 1) (b 2)))
(push 'b (setf (assoc 'b lst) '(b 4)))
;-> b
lst
;-> ((a 1) (b b 4))
; string modification
;------------------------------------------------------------
(set s "Example")
(setf (s 0) "e")
;-> "e"
s
;-> "example"
(setf (s 3) "XYZ")
;-> "XYZ"
s
;-> "exaXYZle"
; using $it for value-dependent updates
;------------------------------------------------------------
(setq lst '((apples 4) (oranges 1)))
(setf (lst 1 1) (+ $it 1))
;-> 2
lst
;-> ((apples 4) (oranges 2))
(set s "Sample")
(setf (s 0) (lower-case $it))
;-> "s"
s
;-> "sample"
sgn
syntax: (sgn num)
syntax: (sgn num exp-1 [exp-2 [exp-3]])
; numeric sign
;------------------------------------------------------------
(sgn -3.5)
;-> -1
(sgn 0)
;-> 0
(sgn 123)
;-> 1
; conditional expressions
;------------------------------------------------------------
(sgn x -1 0 1)
;-> same behavior as (sgn x)
(sgn x -1 1 1)
;-> -1 for negative x, 1 otherwise
(sgn x nil true true)
;-> nil for negative x, true otherwise
(sgn x (abs x) 0)
;-> (abs x) for x < 0, 0 for x = 0, nil otherwise
share
syntax: (share)
syntax: (share int-address)
syntax: (share int-address exp-value)
syntax: (share nil int-address)
; allocate shared memory
;------------------------------------------------------------
(set mem (share))
;-> int-address
; write and read values
;------------------------------------------------------------
(share mem 123)
;-> 123
(share mem)
;-> 123
(share mem "hello world")
;-> "hello world"
(share mem)
;-> "hello world"
(share mem true)
;-> true
(share mem)
;-> true
; store and evaluate expressions
;------------------------------------------------------------
(share mem '(+ 1 2 3 4))
;-> (+ 1 2 3 4)
(eval (share mem))
;-> 10
; unmap shared memory
;------------------------------------------------------------
(share nil mem)
;-> true
signal
syntax: (signal int-signal sym-event-handler | function-event-handler)
syntax: (signal int-signal "ignore" | "default" | "reset")
syntax: (signal int-signal)
; define and install a handler
;------------------------------------------------------------
(constant 'SIGINT 2)
(define (ctrlC-handler)
(println "ctrl-C has been pressed"))
(signal SIGINT 'ctrlC-handler)
; pressing ctrl-C now invokes the handler
;------------------------------------------------------------
ctrl-C has been pressed
; reset handler to startup state
;------------------------------------------------------------
(signal SIGINT "reset")
(signal SIGINT
(fn (s)
(println "signal " s " occurred")))
(signal SIGINT)
;-> sym | nil
(define (signal-handler sig)
(println "received signal: " sig))
(for (s 1 8)
(signal s 'signal-handler))
silent
syntax: (silent [exp-1 [exp-2 ... ]])
; suppress output of a single expression
;------------------------------------------------------------
(silent (my-func))
; equivalent form
;------------------------------------------------------------
(silent)
(my-func)
sin
syntax: (sin num-radians)
(sin 1)
;-> 0.8414709838
(set pi (mul 2 (acos 0)))
;-> 3.141592654
(sin (div pi 2))
;-> 1
sinh
syntax: (sinh num-radians)
(sinh 1)
;-> 1.175201194
(sinh 10)
;-> 11013.23287
(sinh 1000)
;-> inf
(sub (tanh 1) (div (sinh 1) (cosh 1)))
;-> 0
slice
syntax: (slice list int-index [int-length])
syntax: (slice array int-index [int-length])
syntax: (slice str int-index [int-length])
; list slicing
;------------------------------------------------------------
(slice '(a b c d e f) 3 2)
;-> (d e)
(slice '(a b c d e f) 2 -2)
;-> (c d)
(slice '(a b c d e f) 2)
;-> (c d e f)
(slice '(a b c d e f) -4 3)
;-> (c d e)
; array slicing
;------------------------------------------------------------
(set arr (array 3 2 (sequence 1 6)))
;-> ((1 2) (3 4) (5 6))
(slice arr 1 2)
;-> ((3 4) (5 6))
; string slicing (byte-based)
;------------------------------------------------------------
(slice "Hello World" 6 2)
;-> "Wo"
(slice "Hello World" 0 5)
;-> "Hello"
(slice "Hello World" 6)
;-> "World"
(slice "Example" -4 2)
;-> "pl"
; UTF-8 strings: operate on bytes
;------------------------------------------------------------
(join
(slice
(explode "ΩΨΧΦΥΤΣΣΡΠΟΞΝΜΛΚΙΘΗΖΕΔΓΒΑ")
3 5))
;-> "ΦΥΤΣΣ"
slice
syntax: (slice list int-index [int-length])
syntax: (slice array int-index [int-length])
syntax: (slice str int-index [int-length])
; list slicing
;------------------------------------------------------------
(slice '(a b c d e f) 3 2)
;-> (d e)
(slice '(a b c d e f) 2 -2)
;-> (c d)
(slice '(a b c d e f) 2)
;-> (c d e f)
(slice '(a b c d e f) -4 3)
;-> (c d e)
; array slicing
;------------------------------------------------------------
(set A (array 3 2 (sequence 1 6)))
;-> ((1 2) (3 4) (5 6))
(slice A 1 2)
;-> ((3 4) (5 6))
; string slicing (byte-based)
;------------------------------------------------------------
(slice "Hello World" 6 2)
;-> "Wo"
(slice "Hello World" 0 5)
;-> "Hello"
(slice "Hello World" 6)
;-> "World"
(slice "Example" -4 2)
;-> "pl"
; UTF-8 strings: operate on bytes
;------------------------------------------------------------
(join
(slice
(explode "ΩΨΧΦΥΤΣΣΡΠΟΞΝΜΛΚΙΘΗΖΕΔΓΒΑ")
3 5))
;-> "ΦΥΤΣΣ"
sort
syntax: (sort list [func-compare])
syntax: (sort array [func-compare])
; basic sorting
;------------------------------------------------------------
(sort '(v f r t h n m j))
;-> (f h j m n r t v)
(sort '((3 4) (2 1) (1 10)))
;-> ((1 10) (2 1) (3 4))
(sort '((3 4) "hi" 2.8 8 b))
;-> (2.8 8 "hi" b (3 4))
; destructive behavior
;------------------------------------------------------------
(set s '(k a l s))
(sort s)
;-> (a k l s)
s
;-> (a k l s)
; custom order
;------------------------------------------------------------
(sort '(v f r t h n m j) >)
;-> (v t r n m j h f)
(sort s <)
;-> (a k l s)
(sort s >)
;-> (s l k a)
s
;-> (s l k a)
; user-defined comparison
;------------------------------------------------------------
(define (comp x y)
(>= (last x) (last y)))
(set db '((a 3) (g 2) (c 5)))
(sort db comp)
;-> ((c 5) (a 3) (g 2))
; anonymous comparison function
;------------------------------------------------------------
(sort db (fn (x y) (>= (last x) (last y))))
source
syntax: (source)
syntax: (source sym-1 [sym-2 ... ])
(define (double x)
(+ x x))
(source 'double)
;-> "(define (double x)\n (+ x x))\n\n"
spawn
syntax: (spawn sym exp [true])
; parallel computation
;------------------------------------------------------------
(define (primes from to)
(local (plist)
(for (i from to)
(if (= 1 (length (factor i)))
(push i plist -1)))
plist))
(set start (time-of-day))
(spawn 'p1 (primes 1 1000000))
(spawn 'p2 (primes 1000001 2000000))
(spawn 'p3 (primes 2000001 3000000))
(spawn 'p4 (primes 3000001 4000000))
(sync 60000)
(println "time spawn: " (- (time-of-day) start))
; Waiting and polling:
;------------------------------------------------------------
; poll every 2 seconds
(until (sync 2000)
(println "."))
; list pending child process IDs
(until (sync 300)
(println (sync)))
; Abort unfinished tasks:
;------------------------------------------------------------
(if (not (sync 60000))
(begin
(println "aborting unfinished: " (sync))
(abort))
(println "all finished successfully"))
; Recursive spawning:
;------------------------------------------------------------
(define (fibo n)
(local (f1 f2)
(if (< n 2)
1
(begin
(spawn 'f1 (fibo (- n 1)))
(spawn 'f2 (fibo (- n 2)))
(sync 10000)
(+ f1 f2)))))
(fibo 7)
;-> 21
sqrt
syntax: (sqrt num)
(sqrt 10)
;-> 3.16227766
(sqrt 25)
;-> 5
ssq
syntax: (ssq list-vector | array-vector)
(set vector (sequence 1 10))
(ssq vector)
;-> 385
(set vector (array 10 (sequence 1 10)))
(ssq vector)
;-> 385
starts-with
syntax: (starts-with str str-key [num-option])
syntax: (starts-with list exp)
; string prefix
;------------------------------------------------------------
(starts-with "this is useful" "this")
;-> true
(starts-with "this is useful" "THIS")
;-> nil
; regular expression matching
;------------------------------------------------------------
(starts-with "this is useful" "THIS" 1)
;-> true
(starts-with "this is useful" "this|that" 0)
;-> true
; list prefix
;------------------------------------------------------------
(starts-with '(1 2 3 4 5) 1)
;-> true
(starts-with '(a b c d e) 'b)
;-> nil
(starts-with '((+ 3 4) b c d) '(+ 3 4))
;-> true
stats
syntax: (stats list-vector)
(set data '(90 100 130 150 180 200 220 300 350 400))
(println
(format [text]
N = %5d
mean = %8.2f
avdev = %8.2f
sdev = %8.2f
var = %8.2f
skew = %8.2f
kurt = %8.2f
[/text]
(stats data)))
N = 10
mean = 212.00
avdev = 84.40
sdev = 106.12
var = 11262.22
skew = 0.49
kurt = -1.34
string
syntax: (string exp-1 [exp-2 ... ])
(string 'hello)
;-> "hello"
(string 1234)
;-> "1234"
(string '(+ 3 4))
;-> "(+ 3 4)"
(string (+ 3 4) 8)
;-> "78"
(string 'hello " " 123)
;-> "hello 123"
(set buff "ABC\000\000\000")
;-> "ABC\000\000\000"
(length buff)
;-> 6
(string buff)
;-> "ABC"
(length (string buff))
;-> 3
string?
syntax: (string? exp)
(set var "hello")
(string? var)
;-> true
struct
syntax: (struct symbol [str-data-type ... ])
; import C functions working with struct tm
;------------------------------------------------------------
(import "libc.so" "asctime" "char*" "void*")
(import "libc.so" "localtime" "void*" "void*")
; define struct tm (Unix 64-bit layout)
;------------------------------------------------------------
(struct 'tm
"int" ; tm_sec
"int" ; tm_min
"int" ; tm_hour
"int" ; tm_mday
"int" ; tm_mon
"int" ; tm_year
"int" ; tm_wday
"int" ; tm_yday
"int" ; tm_isdst
"long" ; tm_gmtoff
"char*" ; tm_zone
)
; obtain current time
;------------------------------------------------------------
(set today (date-value))
; localtime returns a pointer to struct tm
(set ptr (localtime (address today)))
; unpack struct fields into a list
(unpack tm ptr)
;-> (13 15 7 17 11 111 6 350 0 -28800 "PST")
; format using C library
(asctime ptr)
;-> "Sat Dec 17 07:15:13 2011\n"
; equivalent one-liner
(asctime (localtime (address today)))
; Nested structures:
;------------------------------------------------------------
; define a simple pair
(struct 'pair "char" "char")
;-> pair
; define a structure containing another struct
(struct 'comp "pair" "int")
;-> comp
; pack and unpack nested structures
(pack comp (pack pair 1 2) 3)
;-> "\001\002\000\000\003\000\000\000"
(unpack comp "\001\002\000\000\003\000\000\000")
;-> ((1 2) 3)
sub
syntax: (sub num-1 [num-2 ... ])
(sub 10 8 0.25)
;-> 1.75
(sub 123)
;-> -123
swap
syntax: (swap place-1 place-2)
; swapping elements in a list
;------------------------------------------------------------
(set lst '(a b c d e f))
(swap (first lst) (last lst))
;-> a
lst
;-> (f b c d e a)
; swapping between two lists
;------------------------------------------------------------
(set lst-b '(x y z))
(swap (lst 0) (lst-b -1))
;-> f
lst
;-> (z b c d e a)
lst-b
;-> (x y f)
; swapping array rows
;------------------------------------------------------------
(set A (array 2 3 (sequence 1 6)))
(swap (A 0) (A 1))
;-> (1 2 3)
A
;-> ((4 5 6) (1 2 3))
; swapping symbol values
;------------------------------------------------------------
(set x 1 'y 2)
(swap x y)
;-> 1
x
;-> 2
y
;-> 1
; swapping via assoc and lookup
;------------------------------------------------------------
(set lst '((a 1 2 3) (b 10 20 30)))
(swap (lookup 'a lst -1) (lookup 'b lst 1))
lst
;-> ((a 1 2 10) (b 3 20 30))
(swap (assoc 'a lst) (assoc 'b lst))
lst
;-> ((b 3 20 30) (a 1 2 10))
sym
syntax: (sym string [sym-context [nil-flag]])
syntax: (sym number [sym-context [nil-flag]])
syntax: (sym symbol [sym-context [nil-flag]])
; basic symbol creation
;------------------------------------------------------------
(sym "some")
;-> some
(set (sym "var1") 345)
;-> 345
var1
;-> 345
; specifying contexts
;------------------------------------------------------------
(sym "s" 'ctx)
;-> ctx:s
(sym "s" ctx)
;-> ctx:s
; suppressing symbol creation
;------------------------------------------------------------
(sym "var2" ctx nil)
;-> nil
(sym "var2" ctx)
;-> var2
(sym "var2" ctx nil)
;-> var2
; using sym as associative memory
;------------------------------------------------------------
(set (sym "alpha" 'db) 1.234)
(set (sym "(" 'db) "parenthesis open")
(set (sym 12 'db) "twelve")
(eval (sym "alpha" 'db))
;-> 1.234
(eval (sym "(" 'db))
;-> "parenthesis open"
(eval (sym 12 'db))
;-> "twelve"
; deleting a dynamically created symbol
;------------------------------------------------------------
(delete (sym "alpha" 'db))
;-> true
; using symbols as name sources
;------------------------------------------------------------
(sym 'var1 'ctx)
;-> ctx:var1
; dynamic context population
;------------------------------------------------------------
(define-macro (def-context)
(dolist (s (rest (args)))
(sym s (first (args)))))
(def-context ctx x y z)
(symbols ctx)
;-> (ctx:x ctx:y ctx:z)
symbol?
syntax: (symbol? exp)
(set x 'y)
;-> y
(symbol? x)
;-> true
(symbol? 123)
;-> nil
(symbol? (first '(var x y z)))
;-> true
symbols
syntax: (symbols [context])
; symbols in the current context
;------------------------------------------------------------
(symbols)
; symbols in a specific context
;------------------------------------------------------------
(symbols 'ctx)
(symbols ctx)
(set ct ctx)
(symbols ct)
sync
syntax: (sync int-timeout [func-inlet])
syntax: (sync)
; waiting for child processes
;------------------------------------------------------------
; wait for 10 seconds and process finished children
(sync 10000)
; wait for the maximum time
(sync -1)
; using an inlet function
;------------------------------------------------------------
(define (report pid)
(println "process: " pid " has returned"))
; wait for up to 10 seconds and report finished children
(sync 10000 report)
; querying pending child processes
;------------------------------------------------------------
(sync)
;-> (245 246 247 248)
; periodic polling while waiting
;------------------------------------------------------------
(until (true? (sync 10 report))
(println (time-of-day)))
sys-error
syntax: (sys-error)
syntax: (sys-error int-error)
syntax: (sys-error 0)
; opening a nonexistent file
;------------------------------------------------------------
(open "xyz" "r")
;-> nil
(sys-error)
;-> (2 "No such file or directory")
; resetting the system error
;------------------------------------------------------------
(sys-error 0)
;-> (0 "Unknown error: 0")
(sys-error)
;-> nil
sys-info
syntax: (sys-info [int-idx])
offset description
0 Number of allocated cells
1 Maximum number of cells (constant)
2 Number of symbols
3 Current evaluation / recursion level
4 Environment stack level
5 Maximum call stack depth (constant)
6 Parent process PID or 0
7 Current process PID
8 Version number (integer)
9 Operating system and feature flags
1 = Linux
2 = BSD
3 = macOS
+1024 FFI support enabled
+512 IPv6 support enabled
+256 64-bit runtime
+128 UTF-8 support enabled
+64 Library build
(sys-info)
;-> (429 268435456 402 1 0 2048 0 19453 10406 1155)
(sys-info 3)
;-> 1
(sys-info -2)
;-> 10406
t-test
syntax: (t-test list-vector number-value)
syntax: (t-test list-vector-A list-vector-B [true])
syntax: (t-test list-vector-A list-vector-B float-probability)
index name description
----- ---------- ----------------------------------------
0 mean mean of data in vector
1 value value to compare
2 sdev standard deviation of data
3 mean-error standard error of the mean
4 t t statistic
5 df degrees of freedom
6 p two-tailed probability
; one-sample t-test
;------------------------------------------------------------
(t-test '(3 5 4 2 5 7 4 3) 2.5)
;-> (4.125 2.5 1.552 0.549 2.960 7 0.021)
index name description
----- ------ -----------------------------------------
0 mean-a mean of group A
1 mean-b mean of group B
2 sdev-a standard deviation of group A
3 sdev-b standard deviation of group B
4 t t statistic
5 df degrees of freedom
6 p two-tailed probability
; two independent samples
;------------------------------------------------------------
(set hours-sleep-8 '(5 7 5 3 5 3 3 9))
(set hours-sleep-4 '(8 1 4 6 6 4 1 2))
(t-test hours-sleep-8 hours-sleep-4)
;-> (5 4 2.138 2.563 0.847 14 0.411)
; two related samples
;------------------------------------------------------------
(set mood-pre '(3 0 6 7 4 3 2 1 4))
(set mood-post '(5 1 5 7 10 9 7 11 8))
(t-test mood-pre mood-post true)
;-> (3.333 7 2.236 3.041 -3.143 8 0.0137)
; Welch t-test forced
;------------------------------------------------------------
(t-test '(10 4 7 1 1 6 1 8 2 4)
'(4 6 9 4 6 8 9 3)
1.0)
;-> (4.4 6.125 3.239 2.357 -1.307 15 0.211)
; standard t-test
;------------------------------------------------------------
(t-test '(10 4 7 1 1 6 1 8 2 4)
'(4 6 9 4 6 8 9 3))
;-> (4.4 6.125 3.239 2.357 -1.260 16 0.226)
tan
syntax: (tan num-radians)
(tan 1)
;-> 1.557407725
(set pi (mul 2 (asin 1)))
;-> 3.141592654
(tan (div pi 4))
;-> 1
tanh
syntax: (tanh num-radians)
(tanh 1)
;-> 0.761594156
(tanh 10)
;-> 0.9999999959
(tanh 1000)
;-> 1
(= (tanh 1) (div (sinh 1) (cosh 1)))
;-> true
term
syntax: (term symbol)
(set ctx:var 123)
(set sm 'ctx:var)
(string sm)
;-> "ctx:var"
(term sm)
;-> "var"
; reconstructing the original symbol
;------------------------------------------------------------
(set s 'ctx:var)
(= s (sym (term s) (prefix s)))
;-> true
throw
syntax: (throw exp)
; basic throw and catch
;------------------------------------------------------------
(define (throw-test)
(repeat (x 1000)
(if (= x 500) (throw "interrupted"))))
(catch (throw-test) 'result)
;-> true
result
;-> "interrupted"
; short form returning the thrown value
;------------------------------------------------------------
(catch (throw-test))
;-> "interrupted"
; early exit from an expression block
;------------------------------------------------------------
(catch (begin
...
(if (foo X) (throw X) Y)
...
))
throw-error
syntax: (throw-error exp)
; raising a user-defined error
;------------------------------------------------------------
(define (func x y)
(if (= x 0)
(throw-error "first argument cannot be 0"))
(+ x y))
(func 1 2)
;-> 3
(func 0 2)
;-> ERR: user error : first argument cannot be 0
;-> called from user-defined function func
time
syntax: (time int-year int-month int-day [int-hour int-min int-sec])
syntax: (time list-date-time)
syntax: (time)
time returns the timestamp for the
current system time.(time 2025 7 16)
;-> 1752624000
(time '(2025 7 16))
;-> 1752624000
(time 1970 1 1 0 0 0)
;-> 0
(datelist (time))
;-> (2026 1 3 6 41 26 3 6)
title-case [utf8]
syntax: (title-case str [bool])
(title-case "hello")
;-> "Hello"
(title-case "hELLO" true)
;-> "Hello"
(title-case "hELLO")
;-> "HELLO"
trace
syntax: (trace int-device)
syntax: (trace true)
syntax: (trace nil)
syntax: (trace)
; tracing to a file
;------------------------------------------------------------
(trace (open "trace.txt"))
(f1 x y)
(f2 x)
(trace nil)
; interactive debugger
;------------------------------------------------------------
(trace true)
;-> true
(f1 a b c)
(trace nil)
;-> nil
; setting breakpoints
;------------------------------------------------------------
(define (test-func x)
(trace true)
(+ x 1))
(test-func 10)
; using debug shortcut
;------------------------------------------------------------
(debug (f1 a b c))
trace-highlight
syntax: (trace-highlight str-pre str-post [str-header str-footer])
; replace default markers with >> and <<
;------------------------------------------------------------
(trace-highlight ">>" "<<")
; use terminal control sequences for emphasis
;------------------------------------------------------------
(trace-highlight "\027[1m" "\027[0m")
transpose
syntax: (transpose matrix)
; basic list matrix
;------------------------------------------------------------
(set mtx '((1 2 3) (4 5 6)))
(transpose mtx)
;-> ((1 4) (2 5) (3 6))
; single-row matrix
;------------------------------------------------------------
(transpose (list (sequence 1 5)))
;-> ((1) (2) (3) (4) (5))
; mixed data types
;------------------------------------------------------------
(transpose '((a b) (c d) (e f)))
;-> ((a c e) (b d f))
; array matrix
;------------------------------------------------------------
(set arr (array 2 3 (sequence 1 6)))
(set mtx (transpose arr))
mtx
;-> ((1 4) (2 5) (3 6))
; uneven rows
;------------------------------------------------------------
(set mtx '((1 2 3) (4 5) (7 8 9)))
(transpose mtx)
;-> ((1 4 7) (2 5 8) (3 nil 9))
; non-list row expansion
;------------------------------------------------------------
(set mtx '((1 2 3) X (7 8 9)))
(transpose mtx)
;-> ((1 X 7) (2 X 8) (3 X 9))
trim [utf8]
syntax: (trim str)
syntax: (trim str str-char)
syntax: (trim str str-left-char str-right-char)
(trim " hello \n ")
;-> "hello"
(trim " h e l l o ")
;-> "h e l l o"
(trim "----hello-----" "-")
;-> "hello"
(trim "00012340" "0" "")
;-> "12340"
(trim "1234000" "" "0")
;-> "1234"
(trim "----hello=====" "-" "=")
;-> "hello"
true?
syntax: (true? exp)
(map true? '(x 1 "hi" (a b c) nil ()))
;-> (true true true true nil nil)
(true? nil)
;-> nil
(true? '())
;-> nil
unify
syntax: (unify exp-1 exp-2 [list-env])
; simple matches
;------------------------------------------------------------
(unify 'A 'A)
;-> ()
(unify 'A 123)
;-> ((A 123))
(unify '(A B) '(x y))
;-> ((A x) (B y))
(unify 'abc 'xyz)
;-> nil
; aliasing and structure
;------------------------------------------------------------
(unify '(A B) '(B abc))
;-> ((A abc) (B abc))
(unify '(f A) '(f B))
;-> ((A B))
(unify '(f A) '(g B))
;-> nil
(unify '(f A) 'A)
;-> nil
; nested structures
;------------------------------------------------------------
(unify '(f (g A)) '(f B))
;-> ((B (g A)))
(unify '(f (g A) A) '(f B xyz))
;-> ((B (g xyz)) (A xyz))
; wildcard _
;------------------------------------------------------------
(unify '(A b _) '(x G z))
;-> ((A x) (G b))
(unify '(A b c _) '(x G _ z))
;-> ((A x) (G b))
(unify '(A b _) '(x G (x y z)))
;-> ((A x) (G b))
; using an environment
;------------------------------------------------------------
(unify '(f X) '(f 123))
;-> ((X 123))
(unify '(A B) '(X A) '((X 123)))
;-> ((X 123) (A 123) (B 123))
(set bindings (unify '(f (g A) A) '(f B xyz)))
;-> ((B (g xyz)) (A xyz))
(expand '(f (g A) A) bindings)
;-> (f (g xyz) xyz)
(bind (unify '((A B) C) '((one "two") 3)))
A
;-> one
B
;-> "two"
C
;-> 3
union
syntax: (union list-1 list-2 [list-3 ... ])
(union '(1 3 1 4 4 3) '(2 1 5 6 4))
;-> (1 3 4 2 5 6)
unique
syntax: (unique list)
(unique '(2 3 4 4 6 7 8 7))
;-> (2 3 4 6 7 8)
unless
syntax: (unless exp-condition body)
(unless (starts-with (read-line) "quit")
(process (current-line))
...
(finish))
unpack
syntax: (unpack str-format str-addr-packed)
syntax: (unpack str-format num-addr-packed)
syntax: (unpack struct num-addr-packed)
syntax: (unpack struct str-addr-packed)
code description
---- -------------------------------------------------
c signed 8-bit integer
b unsigned 8-bit integer
d signed 16-bit integer
u unsigned 16-bit integer
ld signed 32-bit integer
lu unsigned 32-bit integer
Ld signed 64-bit integer
Lu unsigned 64-bit integer
f 32-bit float
lf 64-bit double float
sn string of n null-padded ASCII characters
nn n null bytes
> switch to big-endian byte order
< switch to little-endian byte order
; basic packing and unpacking
;------------------------------------------------------------
(pack "c c c" 65 66 67)
;-> "ABC"
(unpack "c c c" "ABC")
;-> (65 66 67)
(set buf (pack "c d u" 10 12345 56789))
(unpack "c d u" buf)
;-> (10 12345 56789)
; strings and floats
;------------------------------------------------------------
(set buf (pack "s10 f" "result" 1.23))
(unpack "s10 f" buf)
;-> ("result\000\000\000\000" 1.230000019)
(set buf (pack "s3 lf" "result" 1.23))
(unpack "s3 f" buf)
;-> ("res" 1.23)
; null padding
;------------------------------------------------------------
(set buf (pack "c n7 c" 11 22))
(unpack "c n7 c" buf)
;-> (11 22)
; byte order control
;------------------------------------------------------------
(set buf (pack "d" 1))
(unpack "d" buf)
;-> (1)
(unpack ">d" buf)
;-> (256)
; different pack and unpack formats
;------------------------------------------------------------
(set buf (pack "s3" "ABC"))
(unpack "c c c" buf)
;-> (65 66 67)
until
syntax: (until exp-condition [body])
(device (open "somefile.txt" "read"))
(set line-count 0)
(until (not (read-line))
(inc line-count))
(close (device))
(print "the file has " line-count " lines\n")
upper-case [utf8]
syntax: (upper-case str)
(upper-case "hello world")
;-> "HELLO WORLD"
utf8
syntax: (utf8 str-unicode)
(unicode "new")
;-> "n\000\000\000e\000\000\000w\000\000\000\000\000\000\000"
(utf8 (unicode "new"))
;-> "new"
; testing for UTF-8 support
;------------------------------------------------------------
(if utf8
(do-utf8-version-of-code)
(do-ascii-version-of-code))
utf8len
syntax: (utf8len str)
(utf8len "我能吞下玻璃而不伤身体。")
;-> 12
(length "我能吞下玻璃而不伤身体。")
;-> 36
uuid
syntax: (uuid [str-node])
; type 4 UUID (random)
;------------------------------------------------------------
(uuid)
;-> "493AAD61-266F-48A9-B99A-33941BEE3607"
; type 1 UUID using a node ID
;------------------------------------------------------------
; node ID for MAC 00:14:51:0a:e0:bc
(set id (pack "cccccc" 0x00 0x14 0x51 0x0a 0xe0 0xbc))
(uuid id)
;-> "0749161C-2EC2-11DB-BBB2-0014510AE0BC"
wait-pid
syntax: (wait-pid int-pid [int-options | nil])
; wait for a specific child
;------------------------------------------------------------
(set pid (fork (my-process)))
(set ret (wait-pid pid))
;-> (8596 0)
(println "process: " pid
" has finished with status: "
(last ret))
; non-blocking polling for any child
;------------------------------------------------------------
(until (not (first (wait-pid -1 nil))))
when
syntax: (when exp-condition body)
(when (read-line)
(set result (analyze (current-line)))
(report result)
(finish))
while
syntax: (while exp-condition body)
(device (open "somefile.txt" "read"))
(set line-count 0)
(while (read-line)
(inc line-count))
(close (device))
(print "the file has " line-count " lines\n")
write
syntax: (write)
syntax: (write int-file str-buffer [int-size])
syntax: (write str str-buffer [int-size])
; writing to a file
;------------------------------------------------------------
(set handle (open "file.ext" "write"))
(write handle data 100)
(write handle "a quick message\n")
; destructive string append
;------------------------------------------------------------
(set str "")
(write str "hello world")
str
;-> "hello world"
; write last read line to stdout
;------------------------------------------------------------
(write)
write-char
syntax: (write-char int-file int-byte1 [int-byte2 ... ])
; slow byte-by-byte file copy
;------------------------------------------------------------
(define (slow-file-copy from-file to-file)
(set in-file (open from-file "read"))
(set out-file (open to-file "write"))
(while (set chr (read-char in-file))
(write-char out-file chr))
(close in-file)
(close out-file)
"finished")
write-file
syntax: (write-file str-file-name str-buffer)
; write encrypted file
;------------------------------------------------------------
(write-file "file.enc"
(encrypt (read-file "/home/user/file") "secret"))
; write to a remote URL
;------------------------------------------------------------
(write-file "http://example.com/message.txt"
"This is a message")
write-line
syntax: (write-line [int-file [str]])
syntax: (write-line str-out [str])
; write a line to a file
;------------------------------------------------------------
(set out (open "file.txt" "write"))
(write-line out "hello there")
(close out)
; write last read line to stdout
;------------------------------------------------------------
(set in (open "init.txt" "read"))
(while (read-line in)
(write-line))
(close in)
; append lines to a string
;------------------------------------------------------------
(set str "")
(write-line str "hello")
(write-line str "world")
str
;-> "hello\nworld\n"
xfer-event
syntax: (xfer-event sym-event-handler | func-event-handler)
syntax: (xfer-event nil)
; monitor download progress
;------------------------------------------------------------
(xfer-event (fn (n)
(println "->" n)))
(length (get-url "http://example.com"))
; sample output:
;-> 73
;-> 799
;-> 1452
;-> 351
;-> 1093
;-> 352
;-> 211
;-> 885
;-> 564
;-> 884
;-> 561
;-> 75
;-> 812
;-> 638
;-> 1452
;-> 801
;-> 5
;-> 927
;-> 11935
; using a named handler
;------------------------------------------------------------
(define (report n)
(println "->" n))
(xfer-event 'report)
xml-error
syntax: (xml-error)
(xml-parse "<tag1>hello</tag1><fin")
;-> nil
(xml-error)
;-> ("expected closing tag: >" 18)
xml-parse
syntax: (xml-parse string-xml [int-options [sym-context [func-callback]]])
(set xml
"<person name='John Doe' tel='555-1212'>nice guy</person>")
(xml-parse xml)
;-> (("ELEMENT" "person"
; (("name" "John Doe") ("tel" "555-1212"))
; (("TEXT" "nice guy"))))
value description
----- ---------------------------------------------
1 suppress whitespace TEXT nodes
2 suppress empty attribute lists
4 suppress COMMENT nodes
8 translate string tags into symbols
16 add SXML attribute tags (@ ...)
; parse without options
;------------------------------------------------------------
(xml-parse (read-file "example.xml"))
; suppress whitespace, empty attributes, and comments
;------------------------------------------------------------
(xml-parse (read-file "example.xml") (+ 1 2 4))
(xml-type-tags nil nil nil nil)
(xml-parse "<msg>Hello World</msg>" (+ 1 2 4 8 16) 'CTX)
;-> ((CTX:msg "Hello World"))
(xml-type-tags nil nil nil nil)
(xml-parse (read-file "example.xml") (+ 1 2 4 8 16))
;-> ((DATABASE (@ (name "example.xml"))
; (FRUIT (NAME "apple") (COLOR "red") (PRICE "0.80"))
; (FRUIT (NAME "orange") (COLOR "orange") (PRICE "1.00"))
; (FRUIT (NAME "banana") (COLOR "yellow") (PRICE "0.60"))))
(define (xml-callback s-expr start size)
(when (or (= (s-expr 0) 'NAME)
(= (s-expr 0) 'COLOR)
(= (s-expr 0) 'PRICE))
(print "parsed expression:" s-expr)
(println ", source:" (start size example-xml))))
(xml-type-tags nil 'cdata '!-- nil)
(xml-parse (read-file "example.xml") (+ 1 2 8) MAIN xml-callback)
xml-type-tags
syntax: (xml-type-tags [exp-text-tag exp-cdata-tag exp-comment-tag exp-element-tag])
; show current XML type tags
;------------------------------------------------------------
(xml-type-tags)
;-> ("TEXT" "CDATA" "COMMENT" "ELEMENT")
; suppress TEXT and ELEMENT, rename CDATA and COMMENT
;------------------------------------------------------------
(xml-type-tags nil 'cdata '!-- nil)
zero? [bigint]
syntax: (zero? exp)
(set value 1.2)
(set var 0)
(zero? value)
;-> nil
(zero? var)
;-> true
(map zero? '(0 0.0 3.4 4))
;-> (true true nil nil)
(map zero? '(nil true 0 0.0 "" ()))
;-> (nil nil true true nil nil)
fin-fv
syntax: (fin-fv num-rate num-nper num-pmt num-pv [int-type])
num-rate is the interest rate
per period. num-nper is the number of periods. num-pmt is
the payment applied each period. num-pv is the principal
value at the beginning of the schedule.int-type is omitted or 0, payments occur at the end
of each period. When int-type is 1, payments occur at the
beginning of each period. The returned value represents
the balance after all interest and payments have been
applied.; end-of-period payment
(fin-fv (div 0.07 12) 240 775.30 -100000)
;-> -0.5544645052
; beginning-of-period payment
(fin-fv (div 0.07 12) 240 775.30 -100000 1)
;-> 54.093...
num-rate must be expressed as the rate per periodint-type controls timing of paymentsnum-pv and num-pmt define cash direction
sta-bayes-query
syntax: (sta-bayes-query list-L context-D [bool-chain [bool-probs]])
list-L
using the trained dictionary context-D. The dictionary
contains token frequencies or probability values for one
or more categories. The function returns one probability
per category.
bool-chain = true):
Posterior values become priors for the next token.
Zero-frequency tokens eliminate the affected category
from subsequent steps.bool-probs is true, dictionary entries are treated
as probabilities instead of raw counts.context-D. A higher
value means a higher estimated probability that the
tokens in list-L belong to that category. Values are real
numbers in [0.0, 1.0]. In Chain Bayesian mode, eliminated
categories may prevent the list from summing to 1.0.
(set Sample:A '(
(sunny 1)
(day 1)
(bright 1)
(sky 1)
))
(set Sample:B '(
(storm 1)
(rain 1)
(dark 1)
(clouds 1)
))
(set Sample:total '(
(A-total 4)
(B-total 4)
))
(sta-bayes-query '(bright sky) Sample)
;-> (0.8571428571 0.1428571428)
; first value = probability for category A
; second value = probability for category B
(sta-bayes-query '(dark rain) Sample)
;-> (0.1428571428 0.8571428571)
; higher value indicates the more likely category
(set C:pos '(8 18))
(set C:neg '(2 72))
(set C:total '(10 90))
(sta-bayes-query '(test-positive) C true)
;-> (0.3076923077 0.6923076923)
(sta-bayes-query '(test-positive test-positive) C true)
;-> (0.64 0.36)
(set P:pos '(0.8 0.2))
(set P:neg '(0.2 0.8))
(set P:total '(0.1 0.9))
(sta-bayes-query '(test-positive) P true true)
;-> (0.3076923077 0.6923076923)
(sta-bayes-query '(test-positive test-positive) P true true)
;-> (0.64 0.36)
(sta-bayes-query '(test-positive test-positive test-positive) P true true)
;-> (0.8767123288 0.1232876712)
list-L should refer to known tokens unless category
elimination is intended.
sta-bayes-train
syntax: (sta-bayes-train list-M1 [list-M2 ... ] sym-context-D)
sym-context-D. Each list-Mi represents a category. The
function counts how many times each token appears in each
category and stores the frequencies inside the dictionary.
The returned value is a list of total token counts per
category.sta-bayes-train constructs the frequency model that
sta-bayes-query evaluates. The minimal text-classification
example shown in sta-bayes-query can be reproduced entirely
using sta-bayes-train. This provides a complete training and
classification workflow inside Rebel.
(sta-bayes-train
'(sunny day bright sky)
'(storm rain dark clouds)
'Weather)
;-> (4 4)
Weather:sunny ;-> (1 0)
Weather:day ;-> (1 0)
Weather:bright ;-> (1 0)
Weather:sky ;-> (1 0)
Weather:storm ;-> (0 1)
Weather:rain ;-> (0 1)
Weather:dark ;-> (0 1)
Weather:clouds ;-> (0 1)
Weather:total ;-> (4 4)
sta-bayes-query in the sample classification examples.(sta-bayes-query '(bright sky) Weather)
;-> (0.8571428571 0.1428571428)
; first value = probability for category A
; second value = probability for category B
(sta-bayes-query '(dark rain) Weather)
;-> (0.1428571428 0.8571428571)
; higher value indicates the more likely category
sta-bayes-train builds the modelsta-bayes-query evaluates new data against that model(sta-bayes-train
'("one" "two" "two" "three")
'("three" "one" "three")
'("one" "two" "three")
'Nums)
;-> (4 3 3)
Nums:_one ;-> (1 1 1)
Nums:_two ;-> (2 0 1)
Nums:_three ;-> (1 2 1)
Nums:total ;-> (4 3 3)
(Nums "two") ;-> (2 0 1)
(Nums "three") ;-> (1 2 1)
sta-bayes-train(set Data:tested-positive '(8 18))
(set Data:tested-negative '(2 72))
(set Data:total '(10 90))
sta-bayes-query.(sta-bayes-train docA-part1 '() 'Model)
(sta-bayes-train docA-part2 '() 'Model)
(sta-bayes-train '() docB-part1 'Model)
(sta-bayes-train '() docB-part2 'Model)
sta-bayes-train will update all counts and maintain correct
totals. All batches must provide the same number of
categories as the original model.
MAIN context
when training from inside another context.
sta-beta
syntax: (sta-beta cum-a num-b)
a and b,
derived from the log Gamma function sta-gammaln. The value
is calculated using the relationbeta(a, b) = exp(gammaln(a) + gammaln(b) - gammaln(a + b))
(sta-beta 1 2)
; → 0.5
sta-gammaln to improve numerical stability
for a wide range of arguments.
sta-betai
syntax: (sta-betai num-x num-a num-b)
x using
parameters a and b. The result corresponds to the
cumulative probability of the Beta distribution at x.
The function is frequently used to obtain cumulative
binomial probabilities.pev = Betai(p, k, N - k + 1)
(sta-betai 0.5 3 8)
; → 0.9453125
a and b must be positive.
sta-binomial
syntax: (sta-binomial int-n int-k float-p)
p
occurs exactly k times in n independent trials. The
function evaluates the classical binomial distribution.
The definition used by Rebel is:binomial = pow(p, k) *
pow(1.0 - p, n - k) *
n! / (k! * (n - k)!)
(sta-binomial 10 3 0.5)
; → 0.1171875
sta-corr
syntax: (sta-corr list-vector-X list-vector-Y)
list-vector-X and list-vector-Y
must have the same length. The function returns six
numeric values describing the linear relationship
between the variables, including effect size, regression
parameters, and significance estimates.r correlation coefficient
b0 regression intercept
b1 regression slope
t t statistic for the slope
df degrees of freedom
p two-tailed probability for t
(set study-time '(90 100 130 150 180 200 220 300 350 400))
;-> (90 100 130 150 180 200 220 300 350 400)
(set test-errors '(25 28 20 20 15 12 13 10 8 6))
;-> (25 28 20 20 15 12 13 10 8 6)
(sta-corr study-time test-errors)
;-> (-0.926 29.241 -0.064 -6.944 8 0.0001190)
sta-crit-chi2
syntax: (sta-crit-chi2 num-probability int-df)
num-probability is the confidence level, and
int-df is the number of degrees of freedom.(sta-crit-chi2 0.01 4)
;-> 13.27670443
sta-crit-f
syntax: (sta-crit-f num-probability int-df1 int-df2)
num-probability is the
desired confidence level, and int-df1 and int-df2 are the
numerator and denominator degrees of freedom. The
returned number is the cutoff point above which an
observed F statistic would be considered significant
under the null hypothesis.(sta-crit-f 0.05 10 12)
;-> 2.753386727
sta-crit-t
syntax: (sta-crit-t num-probability int-df)
num-probability specifies the desired confidence
level, and int-df is the number of degrees of freedom.
The returned value is the threshold above which an
observed t statistic would be judged significant under
the null hypothesis.(sta-crit-t 0.05 14)
;-> 1.761310142
sta-crit-z
syntax: (sta-crit-z num-probability)
num-probability specifies the point on the Z curve where
the cumulative area reaches that probability. The
returned value is used when evaluating statistical
significance or constructing confidence intervals based
on normal theory.(sta-crit-z 0.999)
;-> 3.090232372
gammai
syntax: (gammai num-a num-b)
Q(chi2 | df) = Q(df/2, chi2/2) = gammai(df/2, chi2/2)
(gammai 4 5)
;-> 0.7349740847
gammaln
syntax: (gammaln num-x)
Beta(z, w) = Exp(gammaln(z) + gammaln(w) - gammaln(z + w))
(exp (gammaln 6))
;-> 120