Version: | 2.1.0 |
---|---|
Date: | Dec 11 2023 |
Contents
Function Groups
These are the built-in functions implemented in C.
++ 'word
Arguments
'word | word! |
Return
Value before increment.
Increments series or number bound to word.
-- 'word
Arguments
'word | word! |
Return
Value before decrement.
Decrements series or number bound to word.
_datatype?_ value
Arguments
value |
Return
True if value is a specific datatype.
Each datatype has its own test function which is named the same as the type but ending with '?' rather than a '!'.
This example shows testing for string! and int! types:
string? 20 == false int? 20 == true
See Also
add a b
Arguments
a | int!/double!/vec3! |
b | int!/double!/vec3!/block! |
Return
Sum of two numbers.
The second argument may be a block:
add 0 [4 1 3] == 8
See Also
all tests
Arguments
tests | block! Expressions to test. |
Return
logic!
Return true only when all expressions are true.
See Also
any tests
Arguments
tests | block! Expressions to test. |
Return
Result of first true test or false.
Return true if any expressions are true.
See Also
any-block? value
Arguments
value |
Return
True if value is a block type.
Test if value is one of: block!/paren!/path!/lit-path!/set-path!
any-word? value
Arguments
value |
Return
True if value is a word type.
Test if value is one of: word!/lit-word!/set-word!/get-word!/option!
appair series value1 value2
Arguments
series | Series. |
value1 | First value to append. |
value2 | Second value to append. |
Return
Modified series.
Add a pair of values to the end of series.
See Also
append series value /block /repeat count
Arguments
series | Series or context! |
value | Data to append. |
/block | If series and value are blocks, push value as a single item. |
/repeat | Repeat append. |
count | int! |
Return
Modified series or bound word!.
Add data to end of series.
Examples:
append "apple" 's' == "apples"
append/repeat #{0000} 0xf6 4 == #{0000F6F6F6F6}
dat: [a b] append dat [1 2] == [a b 1 2] append/block dat [3 4] == [a b 1 2 [3 4]]
See Also
bind words context /secure
Arguments
words | word!/block! |
context | word!/context! |
/secure | Unbind any words not found in the context. |
Return
Bound words
See Also
binding? word
Arguments
word | word!/lit-word!/set-word!/get-word!/option! |
Return
context!/datatype!
Get the context which a word is bound to.
See Also
catch body /name word
Arguments
body | block! Code to evaluate. |
/name | Only catch exceptions with a certain name. |
word | word!/block! Names to catch. |
Return
Result of block evaluation or thrown value.
Do body and return any exception thrown.
See Also
change series replacement /slice /part limit
Arguments
series | |
replacement | |
/slice | Remove slice and insert replacement. |
/part | Remove to limit and insert replacement. |
limit | Series or int! |
Return
Series at end of change.
checksum data /sha1 /crc16 /crc32
Arguments
data | binary!/string!/file! |
/sha1 | |
/crc16 | IBM Bisync, USB |
/crc32 | IEEE 802.3, MPEG-2 |
Return
int!/binary!
Computes sha1 checksum by default.
clear series
Arguments
series | series or none!/hash-map! |
Return
Empty series or none!/hash-map!.
Erase to end of series.
See Also
collect types source /unique /into dest
Arguments
types | datatype! |
source | block!/paren! |
/unique | Only add equal values once. |
/into | Add values to dest rather than a new block. |
dest | block! |
Return
New block containing matching values.
Get all values of a certain type from source block.
complement value
Arguments
value | logic!/char!/int!/binary!/bitset! |
Return
Complemented value.
See Also
compress data
Arguments
data | string!/binary! |
Return
binary!
Compress data using either zlib or bzip2, depending upon how Boron was compiled.
See Also
construct object plan
Arguments
object | datatype!/binary!/string! |
plan | string!/block! |
Return
New value.
Make or append values with a detailed specification.
The string! plan is simply pairs of search & replace values applied to a copy of an existing string. Both the search pattern and replacement value types must be char! or string!.
construct "$NAME travels > $CITY" [ '>' "to" "$NAME" "Joseph" "$CITY" "Paris" ] == "Joseph travels to Paris"
It is much more efficient to replace text using construct than calling the replace function multiple times. In the future more rules may be added.
For bitset! the plan is a string in which dash characters denote a range of bits to set. Use two consecutive dashes to include the dash character itself. For example, a bitset of hexidecimal characters would be:
construct bitset! "a-fA-F0-9"
A binary! plan concatenates numbers with specified byte sizes and endianess. These default to 'u32 and 'little-endian respectively. Any words and blocks will be evaluated recursively. Double! and vec3! values are always output as 32-bit floats.
header: [big-endian 0x11 0x2233] data: [u16 0x11 0x2233] construct binary! [header data] == #{000000110000223311003322}
continue
Return
NA
Start next iteration of loop, while, foreach, forall, forever, or map.
See Also
copy value /deep
Arguments
value | |
/deep | If value is a block, copy all sub-blocks. |
Return
New value.
cpu-cycles loop block
Arguments
loop | int! Number of times to evaluate block. |
block | block! |
Return
int!
Get the number of CPU cycles used to evaluate a block.
decode type data
Arguments
type | word! url |
data | string! |
Return
New string with data converted to encoding type.
Undoes URL encoding.
See Also
difference setA setB /case
Arguments
setA | series |
setB | series |
/case | Character case must match when comparing strings. |
Return
New series that contains the elements of setA which are not in setB.
This function generates the set-theoretic difference, not the symmetric difference (the elements unique to both sets).
See Also
dir? path
Arguments
path | file!/string! |
Return
logic! or none! if path does not exist.
Test if path is a directory.
See Also
div a b
Arguments
a | int!/double!/vec3! |
b | int!/double!/vec3! |
Return
Quotient of a divided by b.
See Also
does body
Arguments
body | block! |
Return
func!
Create a function which takes no arguments.
See Also
either test body-t body-f
Arguments
test | Test condition. |
body-t | Value or block to evaluate when true. |
body-f | Value or block to evaluate when false. |
Return
result of body-t if exp is true, or body-f if it is false.
See Also
empty? value
Arguments
value | series or none! |
Return
logic!
Return true if the size of a series is zero, its position is out of range, or the value is none!.
encode type data /bom
Arguments
type | int!/word! 2, 16, 64, latin1, utf8, ucs2, url |
data | binary!/string! |
/bom | Prepend Unicode BOM for utf8 or ucs2 and return binary. |
Return
String or binary with data converted to encoding type.
When data is a string! then the type must be a word! and a new string is returned.
If data is a binary! then the type must be an int! and the input value is returned with only the base indicator modified.
See Also
encoding? data
Arguments
data |
Return
Encoding type or none! if data is not a string!/binary!.
A string! data value will return a word! (latin1, utf8, or ucs2). A binary! data value will return the base int! (2, 16, or 64).
See Also
execute command /in input /out output /err error /spawn /port
Arguments
command | string! |
/in | Provide data via stdin. |
input | binary!/string! |
/out | Store output of command. |
output | binary!/string! |
/err | Store error output of command. |
error | binary!/string! |
/spawn | Run command asynchronously. |
/port | Return port to read spawn output. |
Return
int! status of command or spawn port!
Runs an external program.
If /spawn is used then /in, /out, and /err are ignored.
exists? path
Arguments
path | file!/string! |
Return
True if file or directory exists.
Test if path exists in the filesystem.
See Also
find series value /last /case /part limit
Arguments
series | |
value | Element or pattern to search for. |
/last | Search from end of series. |
/case | Case of characters in strings must match. |
/part | Restrict search to part of series. |
limit | series/int! |
Return
Position of value in series or none!.
first series
Arguments
series | series/coord!/vec3! |
Return
First item in series or none!.
See Also
forall 'ref body
Arguments
'ref | word! Reference to series or none!. |
body | block! Code to evaluate for each element. |
Return
Result of body.
Iterate over each element of a series, changing the reference position.
Example:
a: [1 2 3] forall a [probe a]
[1 2 3] [2 3] [3]
See Also
foreach 'words series body
Arguments
'words | word!/block! Value of element(s). |
series | Series or none! |
body | block! Code to evaluate for each element. |
Return
Result of body.
Iterate over each element of a series.
See Also
forever body
Arguments
body | block! Code to evaluate. |
Return
Result of body.
Repeat body until break or exception thrown.
See Also
format fmt data
Arguments
fmt | block! |
data |
Return
string!
Convert values to formatted string.
The format specification rules are:
int! Field width of the next data item. If negative then right align the item in the field. coord! Field width and limit of the next data item. char!/string! Literal output to string. 'pad char! Set pad character for the following fields.
free resource
Arguments
resource | series/port! |
Return
unset!
Clear series and free its memory buffer or close port.
See Also
ge? a b
Arguments
a | |
b |
Return
True if first value is greater than or equal to the second.
See Also
get word
Arguments
word | Any word type or context! |
Return
Value of word or block of values in context.
See Also
getenv name
Arguments
name | string! |
Return
string! or none!
Get operating system environment variable.
Example:
getenv "PATH" == {/usr/local/bin:/usr/bin:/bin:/usr/games:/home/karl/bin}
See Also
hash string
Arguments
string | word!/string! |
Return
int!
Compute hash value from string (treated as lowercase).
head series
Arguments
series | Series or port! |
Return
Start of series.
For seekable ports, head re-positions it to the start.
See Also
head? series
Arguments
series |
Return
logic! True if position is at the start.
Test if the series position is at the start.
See Also
hostname socket
Arguments
socket | none!/port! |
Return
string!
Get name of local host (if socket is none) or peer (if socket is a port).
if test body
Arguments
test | Test condition. |
body | Value or block to evaluate when true. |
Return
Result of body if test is true, or none! when it is false.
Conditionally evaluate code.
See Also
ifn test body
Arguments
test | Test condition. |
body | Value or block to evaluate when false. |
Return
Result of body if test is false, or none! when it is true.
This is shorthand for "if not test body".
See Also
in context word
Arguments
context | context! |
word | Any word type. |
Return
Word bound to context or none!.
See Also
index? series
Arguments
series | Series, word! or datatype!. |
Return
int!
Get the current position of series.
For words the internal atom value is returned. For datatypes a type bitmask is returned.
See Also
info? path
Arguments
path | file!/string! |
Return
block! of information or none! if path does not exist.
Get information about a file. The values returned are the file type, byte size, modification date, path, and permissions.
Example:
info? %Makefile == [file 9065 2013-10-13T17:15:51-07:00 %Makefile 7,5,5,0]
See Also
infuse block context
Arguments
block | block! |
context | word!/context! |
Return
Modified block.
Replace words with their value in context.
See Also
insert series value /block /part limit /repeat count
Arguments
series | |
value | |
/block | Insert block value as a single item. |
/part | Insert only a limited number of elements from value. |
limit | |
/repeat | Repeat insertion. |
count | int! |
Return
Modified series.
intersect setA setB /case
Arguments
setA | series |
setB | series |
/case | Character case must match when comparing strings. |
Return
New series that contains only the elements common to both sets.
See Also
load file
Arguments
file | file!/string!/binary! |
Return
block! or none! if file is empty.
Load file or serialized data with default bindings.
See Also
loop range body
Arguments
range | int!/block! |
body | block! |
Return
Result of body.
Use 'break in the body to terminate the loop. Use 'continue to immediately start the next iteration.
See Also
lowercase value
Arguments
value | char!/string!/file! |
Return
Value converted to lowercase.
See Also
make prototype attributes
Arguments
prototype | datatype!/context! |
attributes |
Return
New value.
Create a new value.
See Also
make-dir dir /all
Arguments
dir | file!/string! |
/all | Make any missing parent directories. |
Return
unset!
If the directory already exists then the function returns normally. If the specified path points to an existing file or fails for another reason then an error is thrown.
map 'word series body
Arguments
'word | word! |
series | |
body | block! |
Return
Modified series
Replace each element of series with result of body. Use 'break in body to terminate mapping.
mark-sol value /block /clear
Arguments
value | |
/block | Mark block rather than value at block position. |
/clear | Clear start of line flag. |
Return
Value with flag set.
Flag value so that it is printed at the start of a line.
mod a b
Arguments
a | int!/double!/coord! |
b | int!/double!/coord! |
Return
Remainder of a divided by b.
See Also
mold value /contents
Arguments
value | |
/contents | Omit the outer braces from block, context, and vector |
values. |
Return
string!
Convert value to its string form with datatype syntax features.
See Also
mul a b
Arguments
a | int!/double!/vec3! |
b | int!/double!/vec3!/block! |
Return
Product of two numbers.
The second argument may be a block:
mul 3.3 [2 0.4] == 2.64
See Also
negate value
Arguments
value | int!/double!/time!/coord!/vec3!/bitset! |
Return
Negated value.
See Also
open device /read /write /new /nowait
Arguments
device | int!/string!/file!/block! |
/read | Read-only mode. |
/write | Write-only mode. |
/new | Create empty file. |
/nowait | Non-blocking reads. |
Return
port!
Create port!.
See Also
parse input rules /case
Arguments
input | string!/binary!/block! |
rules | block! |
/case | Character case must match when comparing strings. |
Return
True if end of input reached.
See Also
pick series position
Arguments
series | Series or coord!/vec3!/hash-map! |
position | char!/int!/logic! (or key value for hash-map!) |
Return
Value at position or none! if position is out of range.
Note that series use one-based indexing.
If position is a logic! value, then true will return the first series value, and false the second.
A char! position can only be used with a bitset!.
See Also
poke series position value
Arguments
series | series/coord!/vec3!/hash-map! |
position | char!/int!/logic! |
value |
Return
series.
Note that series use one-based indexing.
If position is a logic! value, then true will set the first series value, and false the second.
A char! position can only be used with a bitset!.
See Also
pop series
Arguments
series |
Return
Last item of series or none! if empty.
Removes last item from series and returns it.
prin value
Arguments
value |
Return
unset!
Print reduced value without a trailing linefeed.
See Also
print value
Arguments
value |
Return
unset!
Print reduced value and a trailing linefeed.
See Also
probe value
Arguments
value |
Return
value
Print value with its datatype syntax features.
See Also
quit /return value
Arguments
/return | Returns value as exit status to operating system. |
value | Normally an int! between 0 and 255. |
Return
NA
Exit interpreter. The exit status will be 0 if the return value is not specified.
random data /seed
Arguments
data | logic!/int!/double!/coord!/vec3! or series. |
/seed | Use data as generator seed. |
Return
Random number, series position, or seed if /seed option used.
If data is a number, then a number from 1 through data will be returned.
A call to random/seed must be done before random values will be generated. If seed data is is not an int! then a clock-based seed is used.
read source /text /into buffer /append abuf /part size
Arguments
source | file!/string!/port! |
/text | Read as text rather than binary. |
/into | Put data into existing buffer. |
buffer | binary!/string! |
/append | Append data to existing buffer. |
abuf | binary!/string! |
/part | Read a specific number of bytes. |
size | int! |
Return
binary!/string!/block!/none!
Read binary! or UTF-8 string!. None is returned when nothing is read (e.g. if the end of a file is reached or a TCP socket is disconnected).
When source is a file name the entire file will be read into memory unless /part is used.
If the /text option is used or the /into buffer is a string! then the file is read as UTF-8 data and carriage returns are filtered on Windows.
If source is a directory name then a block containing file names is returned.
See Also
remove series /slice /part number /key kval
Arguments
series | series or none!/hash-map! |
/slice | Remove to end of slice. |
/part | Remove more than one element. |
number | int! |
/key | Remove value from hash-map! |
kval |
Return
series or none!/hash-map!
Remove element at series position.
See Also
remove-each 'words series body
Arguments
'words | word!/block! Value of element(s). |
series | Series or none! |
body | block! Code to evaluate for each element. |
Return
Result of body.
Remove elements when result of body is true.
Example:
items: [1 5 2 3] remove-each i items [gt? i 2] == true probe items == [1 2]
See Also
rename file new-name
Arguments
file | file!/string! |
new-name | file!/string! |
Return
unset! or error thrown.
reserve series size
Arguments
series | |
size | int! Number of elements to reserve. |
Return
Series.
Expand the capacity of series buffer. This cannot be used to make the buffer smaller.
See Also
reverse series /part number
Arguments
series | |
/part | Limit change to part of series. |
number | int! |
Return
series
Reverse the order of elements in a series.
See Also
save dest data
Arguments
dest | file!/string!/port! |
data |
Return
unset!
Convert data to string! then write it. Use 'load to restore the data.
See Also
second series
Arguments
series | series/coord!/vec3! |
Return
Second item in series or none!.
See Also
select series match /last /case
Arguments
series | |
match | |
/last | Search from end of series. |
/case | Case of characters in strings must match |
Return
Value after match or none! if match not found.
serialize data
Arguments
data | block! |
Return
binary!
Pack data into binary image for transport. Series positions, slices, and non-global word bindings are retained.
See Also
set words values
Arguments
words | Any word type or block!/path!. |
values | Any value. |
Return
unset!
Assign a value to one or more words.
set 'a 22 a == 22
If words and values are both a block! then each word in words is set to the corresponding value in values.
set [a b] [1 4.0] a == 1 b == 4.0
See Also
set-addr socket hostname
Arguments
socket | port! |
hostname | string! |
Return
unset!
Set Internet address of socket.
setenv name value
Arguments
name | string! |
value |
Return
value
Set operating system environment variable. Pass a value of none! to unset the variable.
See Also
size? series
Arguments
series |
Return
int!
Length of series from current position to end.
See Also
skip series offset /wrap
Arguments
series | Series or port! |
offset | logic!/int! |
/wrap | Cycle around to other end when new position is out of range. |
Return
Offset series.
If offset is a logic! type then the series will move to the next element if its value is true.
slice start limit
Arguments
start | Series or coord! |
limit | Series or none!/int!/coord! |
Return
Start with adjusted end.
Slice gives a series an end position.
A positive integer limit value sets the length of the slice. If limit is negative, then that number of elements (negated) are removed from the end.
slice "There and back" 5 == "There" slice "There and back" -5 == "There and"
A coord! limit value will modify both the start and the end. The start will be adjusted by the first coord! number (like skip). The second coord! number will set the length or remove from the end (if negative).
slice "There and back" 6,3 == "and" slice "There and back" 6,-3 == "and b"
If limit is from the the same series as start, then the end is simply set to the limit start position.
f: %my_song.mp3 slice f find f '.' == %my_song
Passing a none! limit removes any slice end and returns an un-sliced series.
See Also
sort set /case /group size /field which
Arguments
set | series |
/case | Use case-sensitive comparison with string types. |
/group | Compare groups of elements by first value in group. |
size | int! |
/field | Sort on specified context words or block indices. |
which | block! |
Return
New series with sorted elements.
split input delim /keep
Arguments
input | Series to split. |
delim | Delimiter value. |
/keep | Keep any empty parts left by subsequent delimiters. |
Return
Block of slices from input.
See Also
sub a b
Arguments
a | int!/double!/vec3! |
b | int!/double!/vec3!/block! |
Return
Difference of two numbers.
The second argument may be a block:
sub 4 [3 1 3] == -3
See Also
swap data /group size
Arguments
data | binary!/block! |
/group | Specify number of elements to reverse |
size | int! |
Return
Modified data.
Swap adjacent elements of a series.
See Also
switch value options
Arguments
value | |
options | block! |
Return
Result of selected switch case.
If the size of the options block is odd, then the last value will be the default result.
tail series
Arguments
series | Series or port! |
Return
End of series.
For seekable ports, tail re-positions it to the end.
See Also
terminate series value /dir
Arguments
series | Series to append to. |
value | Value to append. |
/dir | Check if end is '/' or '\'. |
Return
Modified series.
Append value to series only if it does not already end with it.
See Also
third series
Arguments
series | series/coord!/vec3! |
Return
Third item in series or none!.
See Also
thread routine /port
Arguments
routine | string!/block! |
/port | Create thread port. |
Return
Thread port or unset!
Create a new thread to run a routine.
A string! routine argument is preferred as a block! will be converted to a string! before it can be passed to the thread.
If the /port option is used the new thread will have a port! bound to the 'thread-port word that is connected to the one returned from the function. This can be used for bi-directional communication.
Each thread has it's own data store, so series values passed through the port will become empty on write as ownership is transferred. Only one series can be sent through the port on each write, so writing a block! that contains series values will throw an error. Words not bound to the shared environment will become unbound in the reading thread.
throw value /name word
Arguments
value | |
/name | Give exception a name. |
word | word! |
Return
NA
Stop evaluation of the current function and pass an exception up the call stack.
See Also
to-_type_ value
Arguments
value | Any value. |
Return
New datatype!.
Convert a value to another datatype.
Each datatype has its own convert function which is named the same as the type but starting with "to-". For example, to convert a value to a string! use:
to-string 20 == "20"
See Also
to-text value
Arguments
value |
Return
string!
Convert value to text without datatype syntax features.
This example compares to-text with mold:
values: ["str" 'c' [a b]] to-text values == "str c a b" mold values == {["str" 'c' [a b]]}
See Also
trim string /indent /lines
Arguments
string | string! |
/indent | Remove same amount of whitespace from start of all lines. |
/lines | Remove all newlines and extra whitespace. |
Return
Modified string.
try body
Arguments
body | block! Code to evaluate. |
Return
Result of block evaluation or error.
Do body and catch any thrown error!. Other thrown types are ignored and will be passed up the call chain.
See Also
unbind words /deep
Arguments
words | word!/block! |
/deep | If words is a block, unbind all sub-blocks. |
Return
Unbound words
See Also
union setA setB /case
Arguments
setA | series |
setB | series |
/case | Character case must match when comparing strings. |
Return
New series that contains the distinct elements of both sets.
See Also
uppercase value
Arguments
value | char!/string!/file! |
Return
Value converted to uppercase.
See Also
value? value
Arguments
value | Any value. |
Return
True unless value is an unset word.
Determine if a word has already been set.
value? 'blah == false
See Also
values-of context
Arguments
context | context!/hash-map! |
Return
Block of values defined in context or map.
See Also
wait target
Arguments
target | int!/double!/time!/block!/port! |
Return
Port ready for reading or none.
Wait for data on ports.
while exp body
Arguments
exp | block! Test condition. |
body | block! Code to evaluate. |
Return
false
Repeat body as long as exp is true.
See Also
with-flock file body /nowait
Arguments
file | file! Lock file. |
body | block! Code to evaluate. |
/nowait | Don't block if lock fails. |
Return
Result of body or false if locking failed.
Obtains an exclusive file lock, does the body code, then unlocks the file.
words-of context
Arguments
context | context! |
Return
Block of words defined in context.
See Also
write dest data /append /text
Arguments
dest | file!/string!/port! |
data | binary!/string!/context! |
/append | |
/text | Emit new lines with carriage returns on Windows. |
Return
unset!
See Also
xor a b
Arguments
a | logic!/char!/int! |
b | logic!/char!/int!/block! |
Return
Bitwise exclusive OR.
See Also
zero? value
Arguments
value | int!/char!/double! |
Return
logic!
Return true if value is the number zero.
These are the built-in func! functions and aliases.
replace series pat rep /all
Arguments
series | |
pat | Pattern to look for. |
rep | Replacement value. |
/all | Replace all occurances of the pattern, not just the first. |
Return
Modified series at original position.
See Also
split-path path
Arguments
path | file!/string! |
Return
Block with path and filename.
If no directory separator is found, then path (the first block item) will be none!.
term-dir dir
Arguments
dir | file!/string! |
Return
Modified dir
Ensure that the directory has a trailing slash.