Boron Function Reference

Version: 0.3.0
Date: Dec 08 2015

Contents

Function Groups

1   C Functions

These are the built-in functions implemented in C.

++

++ 'word

Arguments

'wordword!

Return

Value before increment.

Increments series or number bound to word.

--

-- 'word

Arguments

'wordword!

Return

Value before decrement.

Decrements series or number bound to word.

_datatype?_

_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

Abs

abs n

Arguments

nint!/decimal!/time!/bignum!

Return

Absolute value of n.

Add

add a b

Arguments

aint!/decimal!/vec3!
bint!/decimal!/vec3!/block!

Return

Sum of two numbers.

The second argument may be a block:

add 0 [4 1 3]
== 8

All

all tests

Arguments

testsblock! Expressions to test.

Return

logic!

Return true only when all expressions are true.

See Also

any

And

and a b

Arguments

alogic!/char!/int!
blogic!/char!/int!/block!

Return

Bitwise AND.

See Also

or, xor

Any

any tests

Arguments

testsblock! Expressions to test.

Return

Result of first true test or false.

Return true if any expressions are true.

See Also

all

Any-block?

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?

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!

Append

append series value /block /repeat count

Arguments

seriesSeries or context!
valueData to append.
/blockIf series and value are blocks, push value as a single item.
/repeatRepeat append.
   countint!

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

Atan

atan n

Arguments

nint!/decimal!

Return

Arc tangent of number.

Bind

bind words context

Arguments

wordsword!/block!
contextword!/context!

Return

Bound words

See Also

Binding?

binding? word

Arguments

wordword!

Return

context!/datatype!

Get the context which a word is bound to.

See Also

Break

break

Return

NA

Exit from loop, while, foreach, or forall.

Case

case options

Arguments

optionsblock!

Return

Result of value following the first true case.

Catch

catch body /name word

Arguments

bodyblock! Code to evaluate.
/nameOnly catch exceptions with a certain name.
   wordword!/block! Names to catch.

Return

Result of block evaluation or thrown value.

Do body and return any exception thrown.

See Also

Change

change series replacement /slice /part limit

Arguments

series
replacement
/sliceRemove slice and insert replacement.
/partRemove to limit and insert replacement.
   limitSeries or int!

Return

Series at end of change.

Change-dir

change-dir dir

Arguments

dirstring!/file!

Return

unset!

Set current working directory.

Checksum

checksum data /sha1 /crc16 /crc32

Arguments

databinary!/string!/file!
/sha1
/crc16IBM Bisync, USB
/crc32IEEE 802.3, MPEG-2

Return

int!/binary!

Computes sha1 checksum by default.

Clear

clear series

Arguments

seriesseries or none!

Return

Empty series or none!.

Erase to end of series.

See Also

Collect

collect types source /unique /into dest

Arguments

typesdatatype!
sourceblock!/paren!
/uniqueOnly add equal values once.
/intoAdd values to dest rather than a new block.
   destblock!

Return

New block containing matching values.

Get all values of a certain type from source block.

Complement

complement value

Arguments

valuelogic!/char!/int!/binary!/bitset!

Return

Complemented value.

See Also

Compress

compress data

Arguments

datastring!/binary!

Return

binary!

Compress data using either zlib or bzip2, depending upon how Boron was compiled.

See Also

Construct

construct object plan

Arguments

objectdatatype!/binary!/string!
planblock!

Return

New value.

Make or append values with a detailed specification.

Copy

copy value /deep

Arguments

value
/deepIf value is a block, copy all sub-blocks.

Return

New value.

Cos

cos n

Arguments

nint!/decimal!

Return

Cosine of number.

Cpu-cycles

cpu-cycles loop block

Arguments

loopint! Number of times to evaluate block.
blockblock!

Return

int!/bignum!

Get the number of CPU cycles used to evaluate a block.

Current-dir

current-dir

Return

File! of current working directory.

Decode

decode type data

Arguments

typeword! url
datastring!

Return

New string with data converted to encoding type.

Undoes URL encoding.

See Also

Decompress

decompress data

Arguments

databinary!

Return

string!/binary!

See Also

Delete

delete file

Arguments

filefile!/string!

Return

unset! or error thrown.

Difference

difference setA setB

Arguments

setAseries
setBseries

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?

dir? path

Arguments

pathfile!/string!

Return

logic! or none! if path does not exist.

Test if path is a directory.

See Also

Div

div a b

Arguments

aint!/decimal!/vec3!
bint!/decimal!/vec3!

Return

Quotient of a divided by b.

See Also

mod

Do

do value

Arguments

value

Return

Result of value.

Does

does body

Arguments

bodyblock!

Return

func!

Create a function which takes no arguments.

See Also

Either

either test body-t body-f

Arguments

testTest condition.
body-tblock! Code to evaluate when true.
body-fblock! Code to evaluate when false.

Return

result of body-t if exp is true, or body-f if it is false.

See Also

if, ifn

Empty?

empty? value

Arguments

valueseries 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

encode type data /bom

Arguments

typeint!/word! 2, 16, 64, latin1, utf8, ucs2, url
databinary!/string!
/bomPrepend 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?

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

Equal?

equal? a b

Arguments

a
b

Return

True if two values are equivalent.

See Also

Execute

execute command /in input /out output /err error /spawn /port

Arguments

commandstring!
/inProvide data via stdin.
   inputbinary!/string!
/outStore output of command.
   outputbinary!/string!
/errStore error output of command.
   errorbinary!/string!
/spawnRun command asynchronously.
/portReturn 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?

exists? path

Arguments

pathfile!/string!

Return

True if file or directory exists.

Test if path exists in the filesystem.

See Also

Exit

exit

Return

NA

Exit from function with result unset.

Find

find series value /last /case /part limit

Arguments

series
valueElement or pattern to search for.
/lastSearch from end of series.
/caseCase of characters in strings must match.
/partRestrict search to part of series.
   limitseries/int!

Return

Position of value in series or none!.

First

first series

Arguments

seriesseries/coord!/vec3!

Return

First item in series or none!.

See Also

Forall

forall 'ref body

Arguments

'refword! Reference to series.
bodyblock! 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

foreach 'words series body

Arguments

'wordsword!/block! Value of element(s).
series
bodyblock! Code to evaluate for each element.

Return

Result of body.

Iterate over each element of a series.

See Also

Forever

forever body

Arguments

bodyblock! Code to evaluate.

Return

Result of body.

Repeat body until break or exception thrown.

See Also

Free

free resource

Arguments

resourceseries/port!

Return

unset!

Clear series and free its memory buffer or close port.

See Also

Func

func spec body

Arguments

specblock!
bodyblock!

Return

func!

Create function.

See Also

Get

get word

Arguments

wordAny word type or context!

Return

Value of word or block of values in context.

See Also

in, set

Getenv

getenv val

Arguments

valstring!

Return

string! or none!

Get operating system environment variable.

Example:

getenv "PATH"
== {/usr/local/bin:/usr/bin:/bin:/usr/games:/home/karl/bin}

Gt?

gt? a b

Arguments

a
b

Return

True if first value is greater than the second.

See Also

eq?, lt?, ne?

Halt

halt

Return

NA

Halt interpreter.

Hash

hash string

Arguments

stringword!/string!

Return

int!

Compute hash value from string (treated as lowercase).

Head?

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

hostname socket

Arguments

socketnone!/port!

Return

string!

Get name of local host (if socket is none) or peer (if socket is a port).

If

if test body

Arguments

testTest condition.
bodyblock! Code to evaluate when true.

Return

Result of body if test is true, or none! when it is false.

Conditionally evaluate code.

See Also

Ifn

ifn test body

Arguments

testTest condition.
bodyblock! Code 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

in context word

Arguments

contextcontext!
wordAny word type.

Return

Word bound to context or none!.

See Also

Index?

index? series

Arguments

seriesSeries or word.

Return

int!

Current position of series.

See Also

Info?

info? path

Arguments

pathfile!/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

infuse block context

Arguments

blockblock!
contextword!/context!

Return

Modified block.

Replace words with their value in context.

See Also

Insert

insert series value /block /part limit /repeat count

Arguments

series
value
/blockInsert block value as a single item.
/partInsert only a limited number of elements from value.
   limit
/repeatRepeat insertion.
   countint!

Return

Modified series.

Intersect

intersect setA setB

Arguments

setAseries
setBseries

Return

New series that contains only the elements common to both sets.

See Also

Last

last series

Arguments

series

Return

Last item in series or none! if empty.

See Also

Load

load file

Arguments

filefile!/string!/binary!

Return

block! or none! if file is empty.

Load file or serialized data with default bindings.

See Also

Loop

loop range body

Arguments

rangeint!/block!
bodyblock!

Return

Result of body.

Use 'break to terminate loop.

See Also

Lowercase

lowercase value

Arguments

valuechar!/string!/file!

Return

Value converted to lowercase.

See Also

Lt?

lt? a b

Arguments

a
b

Return

True if first value is less than the second.

See Also

eq?, gt?, ne?

Make

make prototype attributes

Arguments

prototypedatatype!/context!
attributes

Return

New value.

Create a new value.

See Also

Make-dir

make-dir dir /all

Arguments

dirfile!/string!
/allMake any missing parent directories.

Return

unset!

Map

map 'word series body

Arguments

'wordword!
series
bodyblock!

Return

Modified series

Replace each element of series with result of body. Use 'break in body to terminate mapping.

Mark-sol

mark-sol value /block /clear

Arguments

value
/blockMark block rather than value at block position.
/clearClear start of line flag.

Return

Value with flag set.

Flag value so that it is printed at the start of a line.

Maximum

maximum a b

Arguments

a
b

Return

Greater of two values.

See Also

Minimum

minimum a b

Arguments

a
b

Return

Lesser of two values.

See Also

Mod

mod a b

Arguments

aint!/decimal!/coord!
bint!/decimal!/coord!

Return

Remainder of a divided by b.

See Also

div

Mold

mold value /contents

Arguments

value
/contentsOmit the outer braces from block and context values.

Return

string!

Convert value to its string form with datatype syntax features.

See Also

Mul

mul a b

Arguments

aint!/decimal!/vec3!
bint!/decimal!/vec3!/block!

Return

Product of two numbers.

Ne?

ne? a b

Arguments

a
b

Return

True if two values are not equivalent.

See Also

eq?, gt?, lt?

Negate

negate value

Arguments

valueint!/decimal!/time!/bignum!/coord!/vec3!/bitset!

Return

Negated value.

See Also

Not

not value

Arguments

value

Return

Inverse logic! of value.

See Also

Now

now /date

Arguments

/dateReturn date! rather than time!

Return

time! or date!

Open

open device /read /write /new /nowait

Arguments

deviceint!/string!/file!/block!
/readRead-only mode.
/writeWrite-only mode.
/newCreate empty file.
/nowaitNon-blocking reads.

Return

port!

Create port!.

See Also

Or

or a b

Arguments

alogic!/char!/int!
blogic!/char!/int!/block!

Return

Bitwise OR.

See Also

and, xor

Parse

parse input rules /case

Arguments

inputstring!/block!
rulesblock!
/caseCharacter case must match when comparing strings.

Return

True if end of input reached.

Pick

pick series position

Arguments

seriesSeries or coord!/vec3!
positionint!/logic!

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.

See Also

Poke

poke series position value

Arguments

seriesseries/coord!/vec3!
positionint!/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.

See Also

Pop

pop series

Arguments

series

Return

Last item of series or none! if empty.

Removes last item from series and returns it.

Prin

prin value

Arguments

value

Return

unset!

Print reduced value without a trailing linefeed.

See Also

Print

print value

Arguments

value

Return

unset!

Print reduced value and a trailing linefeed.

See Also

Probe

probe value

Arguments

value

Return

value

Print value with its datatype syntax features.

See Also

Quit

quit /return value

Arguments

/returnReturns value as exit status to operating system.
   valueNormally an int! between 0 and 255.

Return

NA

Exit interpreter. The exit status will be 0 if the return value is not specified.

Random

random data /seed

Arguments

datalogic!/int!/decimal!/coord!/vec3! or series.
/seedUse 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

read source /text /into buffer /append abuf /part size

Arguments

sourcefile!/string!/port!
/textRead as text rather than binary.
/intoPut data into existing buffer.
   bufferbinary!/string!
/appendAppend data to existing buffer.
   abufbinary!/string!
/partRead a specific number of bytes.
   sizeint!

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

Recycle

recycle

Return

NA

Run the garbage collector.

Reduce

reduce value

Arguments

value

Return

Reduced value.

If value is a block then a new block is created with values set to the evaluated results of the original.

Remove

remove series /slice /part number

Arguments

seriesseries or none!
/sliceRemove to end of slice.
/partRemove more than one element.
   numberint!

Return

series or none!

Remove element at series position.

See Also

Remove-each

remove-each 'words series body

Arguments

'wordsword!/block! Value of element(s).
series
bodyblock! 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

rename file new-name

Arguments

filefile!/string!
new-namefile!/string!

Return

unset! or error thrown.

Reserve

reserve series size

Arguments

series
sizeNumber of elements to reserve.

Return

Series.

Expand the capacity of series buffer. This cannot be used to make the buffer smaller.

See Also

Return

return result

Arguments

result

Return

NA

Exit from function with result.

Reverse

reverse series /part number

Arguments

series
/partLimit change to part of series.
   numberint!

Return

series

Reverse the order of elements in a series.

See Also

Same?

same? a b

Arguments

a
b

Return

True if two values are identical.

See Also

Save

save dest data

Arguments

destfile!/string!/port!
data

Return

unset!

Convert data to string! then write it. Use 'load to restore the data.

See Also

Second

second series

Arguments

seriesseries/coord!/vec3!

Return

Second item in series or none!.

See Also

Select

select series match /last /case

Arguments

series
match
/lastSearch from end of series.
/caseCase of characters in strings must match

Return

Value after match or none! if match not found.

Serialize

serialize data

Arguments

datablock!

Return

binary!

Pack data into binary image for transport. Series positions, slices, and non-global word bindings are retained.

See Also

Series?

series? value

Arguments

value

Return

True if value is a series type.

Set

set words values

Arguments

wordsAny word type or block!/path!.
valuesAny 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

set-addr socket hostname

Arguments

socketport!
hostnamestring!

Return

unset!

Set Internet address of socket.

Sin

sin n

Arguments

nint!/decimal!

Return

Sine of number.

Size?

size? series

Arguments

series

Return

int!

Length of series from current position to end.

See Also

Sleep

sleep time

Arguments

timeint!/decimal!/time!

Return

unset!

Delay for a number of seconds.

Slice

slice start limit

Arguments

startSeries or coord!
limitSeries 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

sort set /case /group size /field which

Arguments

setseries
/caseUse case-sensitive comparison with string types.
/groupCompare groups of elements by first value in group.
   sizeint!
/fieldSort on specified context words or block indices.
   whichblock!

Return

New series with sorted elements.

Sqrt

sqrt n

Arguments

nint!/decimal!

Return

Square root of number.

Sub

sub a b

Arguments

aint!/decimal!/vec3!
bint!/decimal!/vec3!/block!

Return

Difference of two numbers.

Swap

swap data /group size

Arguments

databinary!
/groupSpecify number of elements to reverse
   sizeint!

Return

Modified data.

Swap adjacent elements of a series.

See Also

Switch

switch value options

Arguments

value
optionsblock!

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

tail series

Arguments

seriesSeries or port!

Return

End of series.

For seekable ports, tail re-positions it to the end.

See Also

Terminate

terminate series value /dir

Arguments

seriesSeries to append to.
valueValue to append.
/dirCheck if end is '/' or '\'.

Return

Modified series.

Append value to series only if it does not already end with it.

See Also

Third

third series

Arguments

seriesseries/coord!/vec3!

Return

Third item in series or none!.

See Also

Throw

throw value /name word

Arguments

value
/nameGive exception a name.
   wordword!

Return

NA

Stop evaluation of the current function and pass an exception up the call stack.

See Also

To-_type_

to-_type_ value

Arguments

valueAny 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-dec

to-dec number

Arguments

numberint!/bignum!

Return

Number shown as decimal.

To-hex

to-hex number

Arguments

numberchar!/int!/bignum!

Return

Number shown as hexidecimal.

To-text

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

trim string /indent /lines

Arguments

stringstring!
/indentRemove same amount of whitespace from start of all lines.
/linesRemove all newlines and extra whitespace.

Return

Modified string.

Try

try body

Arguments

bodyblock! 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

Type?

type? value

Arguments

value

Return

Datatype of value.

Determine type of value.

See Also

Unbind

unbind words /deep

Arguments

wordsword!/block!
/deepIf words is a block, unbind all sub-blocks.

Return

Unbound words

See Also

Union

union setA setB

Arguments

setAseries
setBseries

Return

New series that contains the distinct elements of both sets.

See Also

Unserialize

unserialize data

Arguments

databinary!

Return

Re-materialized block!.

See Also

Uppercase

uppercase value

Arguments

valuechar!/string!/file!

Return

Value converted to uppercase.

See Also

Value?

value? value

Arguments

valueAny value.

Return

True unless value is an unset word.

Determine if a word has already been set.

value? 'blah
== false

See Also

get, set

Values-of

values-of context

Arguments

contextcontext!

Return

Block of values defined in context.

See Also

Wait

wait target

Arguments

targetint!/decimal!/time!/block!/port!

Return

Port ready for reading or none.

Wait for data on ports.

While

while exp body

Arguments

expblock! Test condition.
bodyblock! Code to evaluate.

Return

false

Repeat body as long as exp is true.

See Also

With-flock

with-flock file body /nowait

Arguments

filefile! Lock file.
bodyblock! Code to evaluate.
/nowaitDon'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

words-of context

Arguments

contextcontext!

Return

Block of words defined in context.

See Also

Write

write dest data /append /text

Arguments

destfile!/string!/port!
databinary!/string!/context!
/append
/textEmit new lines with carriage returns on Windows.

Return

unset!

See Also

Xor

xor a b

Arguments

alogic!/char!/int!
blogic!/char!/int!/block!

Return

Bitwise exclusive OR.

See Also

and, or

Zero?

zero? value

Arguments

valueint!/char!/decimal!

Return

logic!

Return true if value is the number zero.

2   Helper Functions

These are the built-in func! functions and aliases.

Charset

charset spec

Arguments

specstring!

Return

New bitset!

Close

close port

Arguments

port

Return

unset!

Same as free.

See Also

Context

context spec

Arguments

specblock!

Return

New context!

Eq?

eq? a b

Arguments

a
b

Return

logic!

Same as equal?

Error

error message

Arguments

messagestring!

Return

Throws error.

Join

join a b

Arguments

a
b

Return

New series.

Concatenate a and b.

Rejoin

rejoin block

Arguments

block

Return

New series.

Reduce block and concatenate results.

Replace

replace series pat rep /all

Arguments

series
patPattern to look for.
repReplacement value.
/allReplace all occurances of the pattern, not just the first.

Return

Modified series at original position.

Split-path

split-path path

Arguments

pathfile!/string!

Return

Block with path and filename.

If no directory separator is found, then path (the first block item) will be none!.

Tail?

tail? series

Arguments

series

Return

logic!

Same as empty?

See Also

Term-dir

term-dir dir

Arguments

dirfile!/string!

Return

Modified dir

Ensure that the directory has a trailing slash.