next up previous contents index
Next: 2.11.10 threaddict Up: 2.11 Dictionary reference Previous: 2.11.8 sprintsdict   Contents   Index


2.11.9 systemdict

The systemdict dictionary contains most of the operators that are of general use. Although there are no mechanisms that prevent modification of systemdict, programs should not normally need to modify systemdict, since globaldict provides a place for storing globally shared objects. All threads share the same systemdict, which is implicitly locked.

Table 2.10 summarizes the contents of systemdict, and is broken into the following categories:

Table 2.10: systemdict summary
Input(s)
Op/Proc/Var
Output(s)
Description
Operand stack operators
-
mark
mark
Create a mark.
,,,obj
aup
obj ,,,
Rotate stack up one position.
obj ,,,
adn
,,,obj
Rotate stack down one position.
-
count
count
Get the number of objects on ostack.
mark ...
counttomark
mark ...count
Get the depth of the topmost mark on ostack.
obj
dup
obj dup
Duplicate an object.
obj ,,,
bdup
obj ,,,dup
Duplicate bottom object.
objects count
ndup
objects objects
Duplicate objects.
obj ...index
idup
obj ...dup
Duplicate object on ostack at index.
...obj ,,,index
ibdup
...obj ,,,dup
Duplicate object on ostack at index from bottom.
a b
tuck
b a b
Tuck duplicate of top object under second object.
a b
under
a a b
Duplicate second object.
a b
over
a b a
Duplicate second object.
a b
exch
b a
Exchange top two objects.
a b c
up
c a b
Roll top three objects up one.
a ...b count
nup
b a ...
Roll count objects up one.
a b c
dn
b c a
Roll top three objects down one.
a ...b count
ndn
...b a
Roll count objects down one.
...amount
rot
...
Rotate stack up by amount.
region count amount
roll
rolled
Roll count objects up by amount.
obj
pop
-
Remove object.
obj ,,,
bpop
,,,
Remove bottom object.
objects count
npop
-
Remove count objects.
objects ...count
nbpop
...
Remove count objects from bottom.
obj ...index
ipop
...
Remove object at index.
...obj ,,,index
ibpop
...,,,
Remove object at index from bottom.
a b
nip
b
Remove second object.
objects
clear
-
Pop all objects off ostack.
mark ...
cleartomark
-
Remove objects from ostack through topmost mark.
-
ostack
stack
Get a current ostack snapshot.
thread
threadostack
stack
Get a reference to thread's ostack.
Execution, control, and execution stack operators
obj
eval
-
Evaluate object.
boolean obj
if
-
Conditionally evaluate object.
boolean obj
unless
-
Conditionally evaluate object.
boolean a b
ifelse
-
Conditionally evaluate one of two objects.
init inc limit proc
for
-
Iterate with a control variable.
count proc
repeat
-
Iterate a set number of times.
cond proc
while
-
Loop while cond is true.
proc cond
until
-
Loop until cond is false.
proc
loop
-
Loop indefinitely.
array proc
foreach
-
Iterate on array elements.
dict proc
foreach
-
Iterate on dictionary key/value pairs.
stack proc
foreach
-
Iterate on stack elements.
string proc
foreach
-
Iterate on string elements.
-
continue
-
Skip to next iteration of innermost looping context.
-
exit
-
Terminate innermost looping context.
file/string
token
false
Unsuccessfully scan for a token.
file/string
token
rem obj true
Successfully scan for a token
obj
start
-
Evaluate object.
-
quit
-
Unwind to innermost start context.
obj
stopped
boolean
Evaluate object.
-
stop
-
Unwind to innermost stopped or start context.
obj
trapped
false
Snapshot stacks and evaluate object.
obj
trapped
arg true
Snapshot stacks, evaluate object, catch escape , restore snapshot.
arg
escape
-
Unwind to innermost trapped or start context.
name
throw
obj
Throw an error.
-
maxestack
count
Get maximum allowable estack depth.
-
gmaxestack
count
Get default maximum allowable estack depth.
count
setmaxestack
-
Set maximum allowable estack depth.
count
setgmaxestack
-
Set default maximum allowable estack depth.
-
tailopt
boolean
Get whether tail optimization is in effect.
-
gtailopt
boolean
Get default tail optimization setting.
boolean
settailopt
-
Set whether to use tail optimization.
boolean
setgtailopt
-
Set default tail optimization setting.
-
estack
stack
Get a current estack snapshot.
-
estack
stack
Get a current estack snapshot.
thread
threadestack
stack
Get a reference to thread's estack.
-
countestack
count
Get current estack depth.
-
istack
stack
Get a current istack snapshot.
thread
threadistack
stack
Get a reference to thread's istack.
status
die
-
Exit program.
path symbol
modload
-
Load a module.
file symbol
mrequire
-
Search for and load a module.
file
require
-
Search for and evaluate a source file.
prog
path
path/null
Search PATH for prog.
args
exec
-
Overlay a new program and execute it.
args
forkexec
pid
Fork and exec a new process.
args redirects
forkexec
pid
Fork and exec a new process.
pid
waitpid
status
Wait for a program to terminate.
args
system
status
Execute a program.
pid sig
kill
-
Send a signal to a process.
$SIG_GETMASK oset
sigmask
oset
Get signal mask.
how set
sigmask
-
Modify signal mask.
how set oset
sigmask
oset
Modify signal mask.
set
sigpending
set
Get pending signals.
set
sigsuspend
-
Suspend until interrupted by a signal.
set
sigwait
sig
Wait for a signal.
-
pid
pid
Get process ID.
-
ppid
pid
Get parent's process ID.
-
uid
uid
Get the process's user ID.
uid
setuid
boolean
Set the process's user ID.
-
euid
uid
Get the process's effective user ID.
uid
seteuid
boolean
Set the process's effective user ID.
-
gid
gid
Get the process's group ID.
gid
setgid
boolean
Set the process's group ID.
-
egid
gid
Get the process's effective group ID.
gid
setegid
boolean
Set the process's effective group ID.
pid
getpgid
pgid
Get process group ID.
pid pgid
setpgid
-
Set process group ID.
pid
getsid
sid
Get session ID.
-
setsid
sid
Create new session.
-
realtime
nsecs
Get the number of nanoseconds since the epoch.
nsecs
localtime
dict
Get a dict with local time definitions.
nanoseconds
nsleep
-
Nanosleep.
Stack operators
-
(
fino
Begin a stack declaration.
fino objects
)
stack
Create a stack.
-
stack
stack
Create a stack.
stack obj
spush
-
Push object onto stack.
stack obj
sbpush
-
Push object onto bottom of stack.
stack
scount
count
Get the number of objects on a stack.
stack
scounttomark
count
Get the depth of the topmost mark on stack.
stack
sdup
-
Duplicate an object.
stack
sbdup
-
Duplicate bottom object.
stack count
sndup
-
Duplicate objects on stack.
stack index
sidup
-
Duplicate object on stack at index.
stack index
sibdup
-
Duplicate object on stack at index from bottom.
stack
stuck
-
Tuck duplicate of top object on stack under next object on stack.
stack
sunder
-
Duplicate second object on stack.
stack
sover
-
Duplicate second object on stack.
stack
sexch
-
Exchange top objects on stack.
stack
sup
-
Roll top three objects on stack up one.
stack count
snup
-
Roll count objects on stack up one.
stack
saup
-
Roll objects on stack up one.
stack
sdn
-
Roll top three objects on stack down one.
stack count
sndn
-
Roll count objects on stack down one.
stack
sadn
-
Roll objects on stack down one.
stack amount
srot
-
Rotate objects on stack up by amount.
stack count amount
sroll
-
Roll objects on stack.
stack
spop
obj
Pop object off stack.
stack
sbpop
obj
Pop object off bottom of stack.
stack count
snpop
array
Pop count objects off stack.
stack count
snbpop
array
Pop count objects off bottom of stack.
stack index
sipop
obj
Remove object on stack at index.
stack index
sibpop
obj
Remove object on stack at index from bottom.
stack
snip
obj
Remove second object on stack.
stack
sclear
-
Remove all objects on stack.
stack
scleartomark
-
Remove objects from stack down through topmost mark.
(a) (b)
cat
(a b)
Catenate two stacks.
stacks count
ncat
stack
Catenate stacks.
srcstack dststack
copy
dststack
Copy stack contents.
Number (integer, real) and math operators
a b
add
r
Add a and b.
a
inc
r
Add 1 to a.
a b
sub
r
Subtract b from a.
a
dec
r
Subtract 1 from a.
a b
mul
r
Multiply a and b.
a b
div
r
Divide a by b.
a b
idiv
r
Divide a by b (integers).
a b
mod
r
Mod a by b (integers and reals).
a b
pow
r
Raise a to the power of b.
x
exp
r
$e$ (base of natural logarithm) raised to x.
a
sqrt
r
Square root.
a
ln
r
Natural log.
a
log
r
Base 10 log.
a
abs
r
Get the absolute value of a.
a
neg
r
Get the negative of a.
a
ceiling
r
Integer ceiling of a real.
a
floor
r
Integer floor of a real.
a
round
r
Real rounded to integer.
a
trunc
r
Integer from real with truncated fractional.
a
sin
r
Sine in radians.
a
sinh
r
Hyperbolic sine.
a
asin
r
Arcsine.
a
asinh
r
Hyperbolic arcsine.
a
cos
r
Cosine in radians.
a
cosh
r
Hyperbolic cosine.
a
acos
r
Arc cosine.
a
acosh
r
Hyperbolic arc cosine.
x
tan
r
Tangent of x in radians.
x
tanh
r
Hyperbolic tangent.
x
atan
r
Arctangent.
y x
atan2
r
Arctangent in radians of $\frac{y}{x}$.
x
atanh
r
Hyperbolic arctangent.
seed
srand
-
Seed pseudo-random number generator.
-
rand
integer
Get a pseudo-random number.
String operators
length
string
string
Create a string.
string
length
count
Get string length.
string index
get
integer
Get string element.
string index integer
put
-
Set string element.
string index length
getinterval
substring
Get a string interval.
string index substring
putinterval
-
Copy substring into string.
`a' `b'
cat
`ab'
Catenate two strings.
strings count
ncat
string
Catenate strings.
srcstring dststring
copy
dstsubstring
Copy string.
obj depth
sprints
string
Create syntactical string from object.
obj flags
outputs
string
Create formatted string from object.
Name operators
name
length
count
Get name length.
Array operators
-
[
mark
Begin an array declaration.
mark objects
]
array
Construct an array.
length
array
array
Create an array.
array
length
count
Get array length.
array index
get
obj
Get array element.
array index obj
put
-
Set array element.
array index length
getinterval
subarray
Get an array interval.
array index subarray
putinterval
-
Copy subarray into array.
[a] [b]
cat
[a b]
Catenate two arrays.
arrays count
ncat
array
Catenate arrays.
srcarray dstarray
copy
dstsubarray
Copy array.
-
argv
args
Get program arguments.
Dictionary and dictionary stack operators
-
<
mark
Begin a dictionary declaration.
mark kvpairs
>
dict
Construct a dictionary.
-
dict
dict
Create a dictionary.
dict
begin
-
Pust dict onto dstack.
-
end
-
Pop a dictionary off dstack.
key val
def
-
Define key/value pair.
dict key
undef
-
Undefine key in dict.
key
load
val
Look up a key's value.
dict key
known
boolean
Check for key in dict.
key
where
false
Unsuccessfully get topmost dstack dictionary that defines key.
key
where
dict true
Successfully get topmost dstack dictionary that defines key.
dict
length
count
Get number of dictionary key/value pairs.
dict key
get
value
Get dict value associate with key.
dict key value
put
-
Set dict key/value pair.
srcdict dstdict
copy
dstdict
Copy dictionary contents.
-
currentdict
dict
Get topmost dstack dictionary.
-
dstack
stack
Get dstack snapshot.
thread
threaddstack
stack
Get a reference to thread's dstack.
-
countdstack
count
Get number of stacks on dstack.
-
gcdict
dict
Get gcdict.
-
userdict
dict
Get userdict.
-
globaldict
dict
Get globaldict.
-
systemdict
dict
Get systemdict.
-
onyxdict
dict
Get onyxdict.
-
sprintsdict
dict
Get sprintsdict.
-
outputsdict
dict
Get outputsdict.
-
envdict
dict
Get envdict.
-
threadsdict
dict
Get threadsdict.
key val
setenv
-
Set environment variable.
key
unsetenv
-
Unset environment variable.
Class, instance, and handle operators
-
class
class
Create class.
class name
implementor
class/null
Get class that implements name.
class name
implements
boolean
Does class implement name?
class name
method
method
Get class method by name.
class
classname
class/null
Get class's name.
class name/null
setclassname
-
Set class's name.
class
super
super/null
Get class's superclass.
class super/null
setsuper
-
Set class's superclass.
class
methods
dict/null
Get methods dict for class.
class dict/null
setmethods
-
Set methods dict for class.
class/instance
data
dict/null
Get data for class/instance.
class/instance dict/null
setdata
-
Set data for class/instance.
-
instance
instance
Create an instance.
instance
isa
class/null
Get class for instance.
instance class/null
setisa
-
Set class for instance.
instance class
kind
boolean
Is class in instance's inheritance hierarchy?
name super data methods
cdef
-
Create and define a class.
-
this
method/instance
Get topmost object on cstack.
-
cstack
stack
Get cstack snapshot.
thread
threadcstack
stack
Get a reference to thread's cstack.
handle
handletag
tag
Get handle tag.
-
vclass
class
Get vclass.
File and filesystem operators
filename flags
open
file
Open a file.
filename flags mode
open
file
Open a file, creation mode specified.
-
pipe
rfile wfile
Create a pipe.
file
close
-
Close file.
file
read
integer boolean
Read from file.
file string
read
substring boolean
Read from file.
file
readline
string boolean
Read a line from file.
<file dict ...> timeout
poll
[file ...]
Wait for file(s) to change status.
file
bytesavailable
count
Get number of buffered readable bytes.
file
iobuf
count
Get size of I/O buffer.
file count
setiobuf
-
Set size of I/O buffer.
file
nonblocking
boolean
Get non-blocking mode.
file boolean
setnonblocking
-
Set non-blocking mode.
file integer/string
write
false
Write to file.
file integer/string
write
integer/substring true
Write to file.
string
print
-
Print string to stdout.
obj depth
sprint
-
Syntactically print object to stdout.
obj flags
output
-
Formatted print to stdout.
-
pstack
-
Syntactically print ostack elements.
file
flushfile
-
Flush file buffer.
-
flush
-
Flush stdout buffer.
file length
truncate
-
Truncate file.
file offset
seek
-
Move file position pointer.
file
tell
offset
Get file position pointer offset.
path
mkdir
-
Create a directory.
path mode
mkdir
-
Create a directory, mode specified.
path
mkfifo
-
Create a named pipe.
path mode
mkfifo
-
Create a named pipe, mode specified.
old new
rename
-
Rename a file or directory.
file/filename mode
chmod
-
Change file permissions.
file/filename uid gid
chown
-
Change file owner and group.
filename linkname
link
-
Create a hard link.
filename linkname
symlink
-
Create a symbolic link.
filename
unlink
-
Unlink a file.
path
rmdir
-
Remove an empty directory.
file/filename flag
test
boolean
Test a file.
file/filename
status
dict
Get file information.
linkname
readlink
string
Get symbolic link data.
path proc
dirforeach
-
Iterate on directory entries.
-
pwd
path
Get present working directory.
path
cd
-
Change present working directory.
path
chroot
-
Change root directory.
-
stdin
file
Get thread's stdin.
-
stdout
file
Get thread's stdout.
-
stderr
file
Get thread's stderr.
-
gstdin
file
Get global stdin.
-
gstdout
file
Get global stdout.
-
gstderr
file
Get global stderr.
file
setstdin
-
Set thread's stdin.
file
setstdout
-
Set thread's stdout.
file
setstderr
-
Set thread's stderr.
file
setgstdin
-
Set global stdin.
file
setgstdout
-
Set global stdout.
file
setgstderr
-
Set global stderr.
Socket and networking operators
family type proto
socket
sock
Create a socket.
family type
socket
sock
Create a socket.
sock addr port
bindsocket
-
Bind socket to address/port.
sock addr
bindsocket
-
Bind socket to address.
sock path
bindsocket
-
Bind socket to port.
sock backlog
listen
-
Listen for socket connections.
sock
listen
-
Listen for socket connections.
sock
accept
sock
Accept a socket connection.
sock addr port
connect
-
Connect a socket.
sock path
connect
-
Connect a socket.
service
serviceport
port
Get port number for service name.
sock
sockname
dict
Get socket information.
sock level optname
sockopt
optval
Get socket option.
sock optname
sockopt
optval
Get socket option.
sock level optname optval
setsockopt
-
Set socket option.
sock optname optval
setsockopt
-
Set socket option.
sock
peername
dict
Get peer socket information.
sock mesg flags
send
nsend
Send a message.
sock mesg
send
count
Send a message.
sock string flags
recv
substring
Receive a message.
sock string
recv
substring
Receive a message.
family type proto
socketpair
sock sock
Create a socket pair.
family type
socketpair
sock sock
Create a socket pair.
Logical and bitwise operators
a b
lt
boolean
a less than b? (integer/real, string)
a b
le
boolean
a less than or equal to b? (integer/real, string)
a b
eq
boolean
a equal to b? (any type)
a b
ne
boolean
a not equal to b? (any type)
a b
ge
boolean
a greater than or equal to b? (integer/real, string)
a b
gt
boolean
a greater than b? (integer/real, string)
a b
and
r
Logical/bitwise and. (boolean/integer)
a b
or
r
Logical/bitwise or. (boolean/integer)
a b
xor
r
Logical/bitwise exclusive or. (boolean/integer)
a
not
r
Logical/bitwise not. (boolean/integer)
a shift
shift
integer
Bitwise shift.
-
false
false
Return true.
-
true
true
Return false.
Type, conversion, and attribute operators
obj
type
name
Get object type.
obj
lcheck
boolean
Literal?
obj
xcheck
boolean
Executable?
obj
echeck
boolean
Evaluable?
obj
xecheck
boolean
Executable or evaluable?
obj
ccheck
boolean
Callable?
obj
icheck
boolean
Invokable?
obj
fcheck
boolean
Fetchable?
obj
cvl
obj
Set literal attribute.
obj
cve
obj
Set evaluable attribute.
obj
cvx
obj
Set executable attribute.
obj
cvc
obj
Set callable attribute.
obj
cvi
obj
Set invokable attribute.
obj
cvf
obj
Set fetchable attribute.
string
cvn
name
Convert string to name.
obj
cvs
string
Convert object to string.
integer radix
cvrs
string
Convert integer to radix string.
real precision
cvds
string
Convert real to decimal string.
real precision
cves
string
Convert real to exponential string.
Threading and synchronization operators
stack entry
thread
thread
Create and run a thread.
-
self
thread
Get a thread object for the running thread.
thread
join
-
Wait for thread to exit.
thread
detach
-
Detach thread.
-
yield
-
Voluntarily yield the processor.
-
mutex
mutex
Create a mutex.
mutex proc
monitor
-
Evaluate an object under the protection of a mutex.
mutex
lock
-
Acquire mutex.
mutex
trylock
boolean
Try to acquire mutex.
mutex
unlock
-
Release mutex.
-
condition
condition
Create a condition variable.
condition mutex
wait
-
Wait on condition.
condition mutex timeout
timedwait
boolean
Wait on condition with timeout.
condition
signal
-
Signal a condition waiter.
condition
broadcast
-
Signal all condition waiters.
-
currentlocking
boolean
Get implicit locking mode.
boolean
setlocking
-
Set implicit locking mode.
obj
ilocked
boolean
Implicitly locked?
Regular expression operators
string flags
regex
regex
Create a regex object.
string
regex
regex
Create a regex object.
input pattern flags
match
boolean
Find pattern matches in input string.
input pattern
match
boolean
Find pattern matches in input string.
input regex
match
boolean
Find regex matches in input string.
input pattern flags limit
split
array
Split input into an array of substrings.
input pattern flags
split
array
Split input into an array of substrings.
input pattern limit
split
array
Split input into an array of substrings.
input pattern
split
array
Split input into an array of substrings.
input regex limit
split
array
Split input into an array of substrings.
input regex
split
array
Split input into an array of substrings.
integer
submatch
substring
Get capturing subpattern match.
input submatch
offset
offset
Get submatch offset from beginning of input.
pattern template flags
regsub
regsub
Create a regsub object.
pattern template
regsub
regsub
Create a regsub object.
input pattern template flags
subst
output count
Substitute template for pattern matches.
input pattern template
subst
output count
Substitute template for pattern matches.
input regsub
subst
output count
Substitute.
Miscellaneous operators
-
product
string
Get the product string.
-
version
string
Get the version string.
proc
bind
proc
Bind names to operators.
-
null
null
Create a null object.

- ( fino:
Input(s):
None.
Output(s):
fino:
A fino object.
Error(s):
None.
Description:
Push a fino object onto ostack to denote the bottom of a stack that has not yet been constructed.
Example(s):
onyx:0> (
onyx:1> pstack
-fino-
onyx:1>
fino objects ) stack:
Input(s):
fino:
A fino object, usually created by the ) operator.
objects:
0 or more objects.
Output(s):
stack:
A stack object.
Error(s):
unmatchedfino.
Description:
Create a stack object and move all objects from ostack down to the first fino object to the new stack.
Example(s):
onyx:0> ()
onyx:1> 1 sprint
()
onyx:0> (1 2
onyx:3> pstack
2
1
-fino-
onyx:3> )
onyx:1> 1 sprint
(1 2)
onyx:0>
- < mark:
Input(s):
None.
Output(s):
mark:
A mark object.
Error(s):
None.
Description:
Begin a dictionary declaration. See the > operator documentation for more details on dictionary construction.
Example(s):
onyx:0> < 1 sprint
-mark-
onyx:0>
mark kvpairs > dict:
Input(s):
mark:
A mark object.
kvpairs:
Zero or more pairs of non-mark objects, where the first is a key and the second is an associated value.
Output(s):
dict:
A dictionary that contains kvpairs.
Error(s):
rangecheck.
unmatchedmark.
Description:
Construct a dictionary that contains kvpairs.
Example(s):
onyx:0> <
onyx:1> $foo `foo'
onyx:3> $bar `bar'
onyx:5> $biz `biz'
onyx:7> $pop ~pop
onyx:9> >
onyx:1> pstack
<$pop --pop-- $biz `biz' $bar `bar' $foo `foo'>
onyx:1>
- [ mark:
Input(s):
None.
Output(s):
mark:
A mark object.
Error(s):
None.
Description:
Begin an array declaration. See the ] operator documentation for more details on array construction.
Example(s):
onyx:0> [ 1 sprint
-mark-
onyx:0>
mark objects ] array:
Input(s):
mark:
A mark object.
objects:
Zero or more non-mark objects.
Output(s):
array:
An array that contains objects.
Error(s):
unmatchedmark.
Description:
Construct an array that contains all objects on ostack down to the first mark.
Example(s):
onyx:0> mark 1 2 3 ] 1 sprint
[1 2 3]
a abs r:
Input(s):
a:
An integer or real.
Output(s):
r:
Absolute value of a.
Error(s):
stackunderflow.
typecheck.
Description:
Return the absolute value of a.
Example(s):
onyx:0> 5 abs 1 sprint
5
onyx:0> -5 abs 1 sprint
5
onyx:0> 3.14 abs 1 sprint
3.140000e+00
onyx:0> -3.14 abs 1 sprint
3.140000e+00
onyx:0>
sock accept sock:
Input(s):
sock:
A listening socket.
Output(s):
sock:
A socket that is connected to a client.
Error(s):
argcheck.
invalidfileaccess.
ioerror.
neterror.
rangecheck.
stackunderflow.
typecheck.
unregistered.
Description:
Accept a connection and create a socket that is connected to a client.
Example(s):
onyx:0> $AF_INET $SOCK_STREAM socket
onyx:1> dup `localhost' 7777 bindsocket
onyx:1> dup listen
onyx:1> dup accept
onyx:2> dup peername 1 sprint
<$family $AF_INET $address 2130706433 $port 33742>
onyx:2>
a acos r:
Input(s):
a:
An integer or real.
Output(s):
r:
Arc cosine of a in radians.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Return the arc cosine of a in radians.
Example(s):
onyx:0> 1 acos 1 sprint
0.000000e+00
onyx:0>
a acosh r:
Input(s):
a:
An integer or real.
Output(s):
r:
Hyperbolic arc cosine of a.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Return the hyperbolic arc cosine of a.
Example(s):
onyx:0> 10 acosh 1 sprint
2.993223e+00
onyx:0>
a b add r:
Input(s):
a:
An integer or real.
b:
An integer or real.
Output(s):
r:
The sum of a and b.
Error(s):
stackunderflow.
typecheck.
Description:
Return the sum of a and b.
Example(s):
onyx:0> 2 2 add 1 sprint
4
onyx:0> -1 3 add 1 sprint
2
onyx:0> 2.0 3.1 add 1 sprint
5.100000e+00
onyx:0> -1.5 +3e1 add 1 sprint
2.850000e+01
onyx:0>
obj ,,, adn ,,,obj:
Input(s):
obj:
An object.
,,,:
Zero or more objects.
Output(s):
,,,:
Zero or more objects.
obj:
An object.
Error(s):
stackunderflow.
Description:
Rotate stack down one position.
Example(s):
onyx:0> 1 2 3 adn pstack
1
3
2
onyx:3>
a b and r:
Input(s):
a:
An integer or boolean.
b:
The same type as a.
Output(s):
r:
If a and b are integers, their bitwise and, otherwise their logical and.
Error(s):
stackunderflow.
typecheck.
Description:
Return the bitwise and of two integers, or the logical and of two booleans.
Example(s):
onyx:0> false true and 1 sprint
false
onyx:0> true true and 1 sprint
true
onyx:0> 5 3 and 1 sprint
1
onyx:0>
- argv args:
Input(s):
None.
Output(s):
args:
An array of strings. The first string in args is the path of this program, and any additional array elements are the arguments that were passed during invocation.
Error(s):
None.
Description:
Get the argument vector that was used to invoke this program.
Example(s):
onyx:0> argv 1 sprint
[`/usr/local/bin/onyx']
onyx:0>
length array array:
Input(s):
length:
Non-negative number of array elements.
Output(s):
array:
An array of length elements.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Create an array of length elements. The elements are initialized to null objects.
Example(s):
onyx:0> 3 array 1 sprint
[null null null]
onyx:0> 0 array 1 sprint
[]
onyx:0>
a asin r:
Input(s):
a:
An integer or real.
Output(s):
r:
Arc sine of a in radians.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Return the arc sine of a in radians.
Example(s):
onyx:0> -1 asin 1 sprint
-1.570796e+00
onyx:0>
a asinh r:
Input(s):
a:
An integer or real.
Output(s):
r:
Hyperbolic arc sine of a.
Error(s):
stackunderflow.
typecheck.
Description:
Return the hyperbolic arc sine of a.
Example(s):
onyx:0> 10 asinh 1 sprint
2.998223e+00
onyx:0>
x atan r:
Input(s):
x:
An integer or real.
Output(s):
r:
Arctangent of x in radians.
Error(s):
stackunderflow.
typecheck.
Description:
Return the arctangent of x in radians.
Example(s):
onyx:0> 1 atan 1 sprint
7.853982e-01
onyx:0>
y x atan2 r:
Input(s):
y:
An integer or real.
x:
An integer or real.
Output(s):
r:
Arctangent of $\frac{y}{x}$ in radians.
Error(s):
stackunderflow.
typecheck.
Description:
Return the arctangent of in radians.
Example(s):
onyx:0> 1 1 atan2 1 sprint
7.853982e-01
onyx:0> 0 1 atan2 1 sprint
0.000000e+00
onyx:0> -1.0 0 atan2 1 sprint
-1.570796e+00
onyx:0>
x atanh r:
Input(s):
x:
An integer or real.
Output(s):
r:
Hyperbolic arctangent of x.
Error(s):
stackunderflow.
typecheck.
rangecheck.
Description:
Return the hyperbolic arctangent of x.
Example(s):
onyx:0> 0.5 atanh 1 sprint
5.493061e-01
onyx:0>
,,,obj aup obj ,,,:
Input(s):
,,,:
Zero or more objects.
obj:
An object.
Output(s):
obj:
An object.
,,,:
Zero or more objects.
Error(s):
stackunderflow.
Description:
Rotate stack up one position.
Example(s):
onyx:0> 1 2 3 aup pstack
2
1
3
onyx:3>
obj ,,, bdup obj ,,,dup:
Input(s):
obj:
An object.
,,,:
Zero or more objects.
Output(s):
obj:
An object.
,,,:
Zero or more objects.
dup:
A duplicate of obj.
Error(s):
stackunderflow.
Description:
Create a duplicate of the bottom object on ostack and put it on top of ostack.
Example(s):
onyx:0> 1 2 3
onyx:3> bdup pstack
1
3
2
1
onyx:4>
dict begin -:
Input(s):
dict:
A dictionary.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Push dict onto dstack, thereby adding its keys to the namespace.
Example(s):
onyx:0> <$foo `foo'> begin
onyx:0> foo 1 sprint
`foo'
onyx:0>
proc bind proc:
Input(s):
proc:
A procedure (array). proc will be bound even if it is literal, but contained literal arrays will not be recursively bound.
Output(s):
proc:
The same procedure as was passed in.
Error(s):
stackunderflow.
typecheck.
Description:
Recursively bind unbound procedures. Executable names within a procedure are replaced with their values if defined in dstack, in any of the following cases:
  • The value is a literal object.
  • The value is an executable or evaluable operator.
  • The value is an executable or evaluable handle.
  • The value is an executable or evaluable array.

Binding has a large positive impact on performance, since name lookups are thereafter avoided. However, binding is not done by default because there are situations where it is useful to leave procedures unbound:

  • Debugging is easier, since the names associated with objects are still available.
  • Behavior is more dynamic. It is possible to replace a definition on dstack and have it immediately take effect on unbound procedures. Note however that care must be taken when relying on this, since binding is recursive, and a lack of complete understanding of what procedures reference each other can result in undesired bound procedures. For this reason, it is generally best to make dynamic behavior explicit by using evaluable names.
  • There are situations where a program needs to do some setup before binding a procedure, and providing manual control over when binding happens allows more sophisticated use of binding.
Example(s):
onyx:0> {pop sprint {pop sprint}}
onyx:1> dup 2 sprint
{pop sprint {pop sprint}}
onyx:1> bind
onyx:1> dup 2 sprint
{--pop-- _{sprints --print-- `\n' --print-- --flush--}_ {--pop-- -array-}}
onyx:1>
sock addr port bindsocket -:
sock addr bindsocket -:
sock path bindsocket -:
Input(s):
sock:
A socket.
addr:
An IPv4 address or DNS hostname.
port:
An IPv4 port number. If not specified, the OS chooses a port number.
path:
A filesystem path for a Unix-domain socket.
Output(s):
None.
Error(s):
argcheck.
invalidfileaccess.
neterror.
rangecheck.
stackunderflow.
typecheck.
unregistered.
Description:
Bind an address/port to an IPv4 socket, or a filesystem path to a Unix-domain socket.
Example(s):
onyx:0> $AF_INET $SOCK_STREAM socket
onyx:1> dup `localhost' 7777 bindsocket
onyx:1> dup sockname 1 sprint
<$family $AF_INET $address 2130706433 $port 7777>
onyx:1> close
onyx:0> $AF_LOCAL $SOCK_STREAM socket
onyx:1> dup `/tmp/socket' bindsocket
onyx:1> dup sockname 1 sprint
<$family $AF_LOCAL $path `/tmp/socket'>
onyx:1>
obj ,,, bpop ,,,:
Input(s):
,,,:
Zero or more objects.
obj:
An object.
Output(s):
,,,:
Zero or more objects.
Error(s):
stackunderflow.
Description:
Remove the bottom object from ostack and discard it.
Example(s):
onyx:0> 1 2
onyx:2> bpop pstack
2
onyx:1>
condition broadcast -:
Input(s):
condition:
A condition object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Signal all threads that are waiting on condition. If there are no waiters, this operator has no effect.
Example(s):
onyx:0> condition mutex dup lock ostack
onyx:3> {dup lock exch broadcast unlock}
onyx:4> thread 3 1 roll
onyx:3> dup 3 1 roll
onyx:4> wait unlock join
onyx:0>
file bytesavailable count:
Input(s):
file:
A file object.
Output(s):
count:
Number of buffered readable bytes.
Error(s):
stackunderflow.
typecheck.
Description:
Get the number of buffered readable bytes that can be read without the possibility of blocking.
Example(s):
onyx:0> `/tmp/foo' `w+' open
onyx:1> dup `Hello\n' write
onyx:1> dup `Goodbye\n' write
onyx:1> dup 0 seek
onyx:1> dup readline 1 sprint 1 sprint
false
`Hello'
onyx:1> dup bytesavailable 1 sprint
8
onyx:1>
[a] [b] cat [a b]:
(a) (b) cat (a b):
`a' `b' cat `ab':
Input(s):
a:
An array, stack, or string.
b:
An array, stack, or string.
Output(s):
ab:
The catenation of a and b.
Error(s):
stackunderflow.
typecheck.
Description:
Catenate two arrays, strings, or stacks.
Example(s):
onyx:0> [`a'] [`b'] cat
onyx:1> 1 sprint
[`a' `b']
onyx:0> (`a') (`b') cat
onyx:1> 1 sprint
(`a' `b')
onyx:0> `a' `b' cat
onyx:1> 1 sprint
`ab'
onyx:0>
obj ccheck boolean:
Input(s):
obj:
An object.
Output(s):
boolean:
True if obj has the callable attribute, false otherwise.
Error(s):
stackunderflow.
Description:
Check obj for callable attribute.
Example(s):
onyx:0> $name ccheck 1 sprint
false
onyx:0> $name cvc ccheck 1 sprint
true
onyx:0>
path cd -:
Input(s):
path:
A string that represents a filesystem path.
Output(s):
None.
Error(s):
invalidaccess.
ioerror.
stackunderflow.
typecheck.
Description:
Change the present working directory to path.
Example(s):
onyx:0> pwd 1 sprint
`/usr/local'
onyx:0> `bin' cd
onyx:0> pwd 1 sprint
`/usr/local/bin'
onyx:0>
name super data methods cdef -:
Input(s):
name:
An object (usually a name) to set the class's name to and associate the class with.
super:
A superclass, or null.
data:
A dictionary of data definitions, or null.
methods:
A dictionary of method definitions, or null.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Create a new class with name as its name, super as its superclass, data as its data definitions, and methods as its method definitions. Define name in currentdict to be the class.
Example(s):
onyx:0> $fooclass vclass <$foodata `foo'> <$foomethod {`hi' 1 sprint}> cdef
onyx:0> fooclass 1 sprint
-class-
onyx:0> fooclass:foomethod
`hi'
onyx:0>
a ceiling r:
Input(s):
a:
An integer or real.
Output(s):
r:
Integer ceiling of a.
Error(s):
stackunderflow.
typecheck.
Description:
Return the integer ceiling of a.
Example(s):
onyx:0> -1.51 ceiling 1 sprint
-1
onyx:0> -1.49 ceiling 1 sprint
-1
onyx:0> 0 ceiling 1 sprint
0
onyx:0> 1.49 ceiling 1 sprint
2
onyx:0> 1.51 ceiling 1 sprint
2
onyx:0>
file/filename mode chmod -:
Input(s):
file:
A file object.
filename:
A string that represents a filename.
mode:
An integer that represents a Unix file mode.
Output(s):
None.
Error(s):
invalidfileaccess.
ioerror.
rangecheck.
stackunderflow.
typecheck.
unregistered.
Description:
Example(s):
onyx:0> `/tmp/tdir' 8@755 mkdir
onyx:0> `/tmp/tdir' status $mode get 1 sprint
16877
onyx:0> `/tmp/tdir' `r' open
onyx:1> dup 8@555 chmod
onyx:1> `/tmp/tdir' status $mode get 1 sprint
16749
onyx:1>
file/filename uid gid chown -:
Input(s):
file:
A file object.
filename:
A string that represents a filename.
uid:
An integer that represents a user ID.
gid:
An integer that represents a group ID.
Output(s):
None.
Error(s):
invalidfileaccess.
ioerror.
rangecheck.
stackunderflow.
typecheck.
unregistered.
Description:
Change the owner and group of a file.
Example(s):
onyx:0> `/tmp/tdir' 8@755 mkdir
onyx:0> `/tmp/tdir' status
onyx:1> dup $uid get 1 sprint
1001
onyx:1> $gid get 1 sprint
0
onyx:0> `/tmp/tdir' 1001 1001 chown
onyx:0> `/tmp/tdir' status
onyx:1> dup $uid get 1 sprint
1001
onyx:1> $gid get 1 sprint
1001
onyx:0>
path chroot -:
Input(s):
path:
A string that represents a filesystem path.
Output(s):
None.
Error(s):
invalidaccess.
ioerror.
stackunderflow.
typecheck.
Description:
Change the root directory to path. This operator requires super-user priviledges.
Example(s):
onyx:0> pwd 1 sprint
`/home/jasone/cw/devroot'
onyx:0> `/home/jasone' chroot
onyx:0> pwd 1 sprint
`/cw/devroot'
onyx:0>
- class class:
Input(s):
None.
Output(s):
class:
A class object.
Error(s):
None.
Description:
Create a class object.
Example(s):
onyx:0> class 1 sprint
-class-
onyx:0>
class classname -:
Input(s):
class:
A class object.
Output(s):
name/null:
A name or null object.
Error(s):
stackunderflow.
typecheck.
Description:
Get class's name.
Example(s):
onyx:0> class classname 1 sprint
null
onyx:0> vclass classname 1 sprint
$vclass
onyx:0>
objects clear -:
Input(s):
objects:
All objects on ostack.
Output(s):
None.
Error(s):
None.
Description:
Pop all objects off of ostack.
Example(s):
onyx:0> 1 2 3 pstack
3
2
1
onyx:3> clear pstack
onyx:0>
mark ... cleartomark -:
Input(s):
...:
Zero or more objects.
mark:
A mark object.
Output(s):
None.
Error(s):
unmatchedmark.
Description:
Remove objects from ostack down to and including the topmost mark.
Example(s):
onyx:0> 3 mark 1 0 pstack
0
1
-mark-
3
onyx:4> cleartomark pstack
3
onyx:1>
file close -:
Input(s):
file:
A file object.
Output(s):
None.
Error(s):
ioerror.
stackunderflow.
typecheck.
Description:
Close a file.
Example(s):
onyx:0> `/tmp/foo' `w' open
onyx:1> close
onyx:0>
- condition condition:
Input(s):
None.
Output(s):
condition:
A condition object.
Error(s):
None.
Description:
Create a condition object.
Example(s):
onyx:0> condition 1 sprint
-condition-
onyx:0>
sock addr port connect -:
sock path connect -:
Input(s):
sock:
A socket.
addr:
An IPv4 address or DNS hostname.
port:
An IPv4 port number. If not specified, the OS chooses a port number.
path:
A filesystem path for a Unix-domain socket.
Output(s):
None.
Error(s):
argcheck.
invalidfileaccess.
neterror.
stackunderflow.
typecheck.
unregistered.
Description:
Connect sock.
Example(s):
onyx:0> $AF_INET $SOCK_STREAM socket
onyx:1> dup `localhost' 7777 connect
onyx:1>
- continue -:
Input(s):
None.
Output(s):
None.
Error(s):
None.
Description:
Terminate the current iteration of the innermost enclosing context, and start at the beginning of the next iteration. This operator can be called within the looping context of for , repeat , while , until , loop , foreach , and dirforeach .
Example(s):
onyx:0> 1 1 5 {1 sprint continue bang} for
1
2
3
4
5
onyx:0>
srcarray dstarray copy dstsubarray:
srcdict dstdict copy dstdict:
srcstack dststack copy dststack:
srcstring dststring copy dstsubstring:
Input(s):
srcarray:
An array object.
srcdict:
A dict object.
srcstack:
A stack object.
srcstring:
A string object.
dstarray:
An array object, at least as long as srcarray.
dstdict:
A dict object.
dststack:
A stack object.
dststring:
A string object, at least as long as srcstring.
Output(s):
dstsubarray:
A subarray of dstarray, with the same contents as srcarray.
dstdict:
The same object as the input dstdict, but with the contents of srcdict inserted.
dststack:
The same object as the input dststack, but with the contents of srcstack pushed.
dstsubstring:
A substring of dststring, with the same contents as srcstring.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Copy from one object to another. Array and string copying are destructive; dictionary and stack copying are not.
Example(s):
onyx:0> [`a'] [`b' `c'] copy 1 sprint
[`a']
onyx:0> <$foo `foo'> <$bar `bar'> copy 1 sprint
<$bar `bar' $foo `foo'>
onyx:1> (1 2) (3 4) copy 1 sprint
(3 4 1 2)
onyx:1> `a' `bc' copy 1 sprint
`a'
onyx:1>
a cos r:
Input(s):
a:
An integer or real.
Output(s):
r:
Cosine of a in radians.
Error(s):
stackunderflow.
typecheck.
Description:
Return the cosine of a in radians.
Example(s):
onyx:0> 0 cos 1 sprint
1.000000e+00
onyx:0> 3.14 cos 1 sprint
-9.999987e-01
onyx:0> 3.1415927 cos 1 sprint
-1.000000e+00
onyx:0>
a cosh r:
Input(s):
a:
An integer or real.
Output(s):
r:
Hyperbolic cosine of a in radians.
Error(s):
stackunderflow.
typecheck.
Description:
Return the hyperbolic cosine of a in radians.
Example(s):
onyx:0> 3 cosh 1 sprint
1.006766e+01
onyx:0>
- count count:
Input(s):
None.
Output(s):
count:
The number of objects on ostack.
Error(s):
None.
Description:
Get the number of objects on ostack.
Example(s):
onyx:0> 2 1 0 count pstack
3
0
1
2
onyx:4>
- countdstack count:
Input(s):
None.
Output(s):
count:
Number of dictionaries on dstack.
Error(s):
None.
Description:
Get the number of dictionaries on dstack.
Example(s):
onyx:0> countdstack 1 sprint
4
onyx:0> dict begin
onyx:0> countdstack 1 sprint
5
onyx:0>
- countestack count:
Input(s):
None.
Output(s):
count:
The number of objects currently on the execution stack (recursion depth).
Error(s):
None.
Description:
Get the current number of objects on the execution stack.
Example(s):
onyx:0> countestack 1 sprint
3
onyx:0> estack 1 sprint
(--start-- -file- --estack--)
onyx:0>
mark ... counttomark mark ...count:
Input(s):
...:
Zero or more objects.
mark:
A mark object.
Output(s):
...:
count objects.
mark:
The same mark that was passed in.
count:
The depth of mark on ostack.
Error(s):
unmatchedmark.
Description:
Get the depth of the topmost mark on ostack.
Example(s):
onyx:0> 4 mark 2 1 0 counttomark 1 sprint
3
onyx:5>
- cstack stack:
Input(s):
None.
Output(s):
stack:
A snapshot of cstack.
Error(s):
None.
Description:
Get a snapshot of cstack.
Example(s):
onyx:0> cstack 1 sprint
()
onyx:0>
- currentdict dict:
Input(s):
None.
Output(s):
dict:
Topmost stack on dstack.
Error(s):
None.
Description:
Get the topmost dictionary on dstack.
Example(s):
onyx:0> <$foo `foo'> begin
onyx:0> currentdict 1 sprint
<$foo `foo'>
onyx:0>
- currentlocking boolean:
Input(s):
None.
Output(s):
boolean:
If false, new objects are created with implicit locking disabled. Otherwise, new objects are created with implicit locking enabled.
Error(s):
None.
Description:
Get the current implicit locking mode. See Section 2.7.1 for implicit synchronization details.
Example(s):
onyx:0> currentlocking 1 sprint
false
onyx:0> true setlocking
onyx:0> currentlocking 1 sprint
true
onyx:0>
obj cvc obj:
Input(s):
obj:
An object.
Output(s):
obj:
The same object that was passed in, but with the callable attribute set.
Error(s):
stackunderflow.
Description:
Set the callable attribute for obj.
Example(s):
onyx:0> $foo cvc 1 sprint
:foo
onyx:0>
real precision cvds string:
Input(s):
real:
A real.
precision:
Number of digits after the decimal point to show. If negative, do not show trailing zeros.
Output(s):
string:
A string representation of real in decimal form with precision digits of decimal precision.
Error(s):
stackunderflow.
typecheck.
Description:
Convert real to a string representation in decimal notation, with precision digits of decimal precision.
Example(s):
onyx:0> 42.3 0 cvds 1 sprint
`42'
onyx:0> 42.3 1 cvds 1 sprint
`42.3'
onyx:0> -42.3 4 cvds 1 sprint
`-42.3000'
onyx:0> -43.3 -4 cvds 1 sprint
`-42.3'
onyx:0>
obj cve obj:
Input(s):
obj:
An object.
Output(s):
obj:
The same object that was passed in, but with the evaluable attribute set.
Error(s):
stackunderflow.
Description:
Set the evaluable attribute for obj.
Example(s):
onyx:0> [1 2 3] cve 1 sprint
_{1 2 3}_
onyx:0>
real precision cves string:
Input(s):
real:
A real.
precision:
Number of digits after the decimal point to show.
Output(s):
string:
A string representation of real in exponential form with precision digits of decimal precision.
Error(s):
stackunderflow.
typecheck.
Description:
Convert real to a string representation in exponential notation, with precision digits of decimal precision.
Example(s):
onyx:0> 42.3 0 cves 1 sprint
`4e+01'
onyx:0> 42.3 1 cves 1 sprint
`4.2e+01'
onyx:0> 42.3 2 cves 1 sprint
`4.23e+01'
onyx:0> -42.3 5 cves 1 sprint
`-4.23000e+01'
onyx:0>
obj cvf obj:
Input(s):
obj:
An object.
Output(s):
obj:
The same object that was passed in, but with the fetchable attribute set.
Error(s):
stackunderflow.
Description:
Set the fetchable attribute for obj.
Example(s):
onyx:0> $foo cvf 1 sprint
,foo
onyx:0>
obj cvi obj:
Input(s):
obj:
An object.
Output(s):
obj:
The same object that was passed in, but with the invokable attribute set.
Error(s):
stackunderflow.
Description:
Set the invokable attribute for obj.
Example(s):
onyx:0> $foo cvi 1 sprint
;foo
onyx:0>
obj cvl obj:
Input(s):
obj:
An object.
Output(s):
obj:
The same object that was passed in, but with the literal attribute set.
Error(s):
stackunderflow.
Description:
Set the literal attribute for obj.
Example(s):
onyx:0> {1 2 3} cvl 1 sprint
[1 2 3]
onyx:0>
string cvn name:
Input(s):
string:
A string.
Output(s):
name:
A literal name that corresponds to string.
Error(s):
stackunderflow.
typecheck.
Description:
Convert string to a literal name.
Example(s):
onyx:0> `foo' cvn 1 sprint
$foo
onyx:0>
integer radix cvrs string:
Input(s):
integer:
An integer.
radix:
A numerical base, from 2 to 36, inclusive.
Output(s):
string:
A string representation of integer in base radix.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Convert integer to a string representation in base radix.
Example(s):
onyx:0> 42 2 cvrs 1 sprint
`101010'
onyx:0> 42 16 cvrs 1 sprint
`2a'
onyx:0>
obj cvs string:
Input(s):
obj:
An object.
Output(s):
string:
A string representation of obj. The string depends on the type of obj:
boolean:
`true' or `false'.
name:
The string representation of the name.
integer:
The integer in base 10.
operator:
The string representation of the operator name or `-operator-'.
real:
The real in exponential notation.
string:
A printable representation of obj. The result can be evaluated to produce the original string.
Other types:
`-nostringval-'.
Error(s):
stackunderflow.
Description:
Convert obj to a string representation.
Example(s):
onyx:0> true cvs 1 sprint
`true'
onyx:0> $foo cvs 1 sprint
`foo'
onyx:0> 42 cvs 1 sprint
`42'
onyx:0> ~pop cvs 1 sprint
`pop'
onyx:0> 42.0 cvs 1 sprint
`4.200000e+01'
onyx:0> `foo\nbar\\biz\`baz' cvs 1 sprint
`\`foo\\nbar\\\\biz\\\`baz\''
onyx:0> mutex cvs 1 sprint
`--nostringval--'
onyx:0>
obj cvx obj:
Input(s):
obj:
An object.
Output(s):
obj:
The same object that was passed in, but with the executable attribute set.
Error(s):
stackunderflow.
Description:
Set the executable attribute for obj.
Example(s):
onyx:0> [1 2 3] cvx 1 sprint
{1 2 3}
onyx:0>
class/instance data dict/null:
Input(s):
class/instance:
A class or instance object.
Output(s):
dict/null:
A dict or null object.
Error(s):
stackunderflow.
typecheck.
Description:
Get the data associated with class or instance.
Example(s):
onyx:0> vclass data 1 sprint
<>
onyx:0>
a dec r:
Input(s):
a:
An integer.
Output(s):
r:
$a - 1$.
Error(s):
stackunderflow.
typecheck.
Description:
Subtract one from a.
Example(s):
onyx:0> 1 dec 1 sprint
0
onyx:0>
key val def -:
Input(s):
key:
An object.
val:
A value associated with key.
Output(s):
None.
Error(s):
stackunderflow.
Description:
Define key with associated value val in the topmost dictionary on dstack. If key is already defined in that dictionary, the old definition is replaced.
Example(s):
onyx:0> $foo `foo' def
onyx:0> foo 1 sprint
`foo'
onyx:0> $foo `FOO' def
onyx:0> foo 1 sprint
`FOO'
onyx:0>
thread detach -:
Input(s):
thread:
A thread object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Detach thread so that its resources will be automatically reclaimed after it exits. A thread may only be detached or joined once; any attempt to do so more than once results in undefined behavior (likely crash).
Example(s):
onyx:0> (1 2) {add 1 sprint self detach} thread
3
onyx:1>
- dict dict:
Input(s):
None.
Output(s):
dict:
An empty dictionary.
Error(s):
None.
Description:
Create an empty dictionary.
Example(s):
onyx:0> dict 1 sprint
<>
onyx:0>
status die -:
Input(s):
status:
A integer from 0 to 255 that is used as the program exit code.
Output(s):
None.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Exit the program with exit code status.
Example(s):
onyx:0> 1 die
path proc dirforeach -:
Input(s):
path:
A string that represents a filesystem path.
proc:
An object to be executed.
Output(s):
None.
Error(s):
invalidaccess.
ioerror.
stackunderflow.
typecheck.
Description:
For each entry in the directory represented by path except for ``.'' and ``..'', push a string that represents the entry onto ostack and execute proc. This operator supports the continue and exit operators.
Example(s):
onyx:0> pwd {1 sprint} dirforeach
`CVS'
`.cvsignore'
`Cookfile'
`Cookfile.inc'
`latex'
`Cookfile.inc.in'
onyx:0> pwd {`Cookfile.inc' match
     {pop `Yes: ' print 1 sprint pop exit}
     {`Not: ' print 1 sprint} ifelse
} dirforeach
Not: `CVS'
Not: `.cvsignore'
Not: `Cookfile'
Yes: `Cookfile.inc'
onyx:0>
a b div r:
Input(s):
a:
An integer or real.
b:
A non-zero integer or real.
Output(s):
r:
The quotient of a divided by b.
Error(s):
stackunderflow.
typecheck.
undefinedresult.
Description:
Return the quotient of a divided by b.
Example(s):
onyx:0> 4 2 div 1 sprint
2.000000e+00
onyx:0> 5 2.0 div 1 sprint
2.500000e+00
onyx:0> 5.0 0 div
Error $undefinedresult
ostack: (5.000000e+00 0)
dstack: (-dict- -dict- -dict- -dict-)
cstack: ()
estack/istack trace (0..2):
0:      --div--
1:      -file-
2:      --start--
onyx:3>
a b c dn b c a:
Input(s):
a:
An object.
b:
An object.
c:
An object.
Output(s):
b:
An object.
c:
An object.
a:
An object.
Error(s):
stackunderflow.
Description:
Rotate the top three objects on ostack down one position.
Example(s):
onyx:0> `a' `b' `c' `d' dn pstack
`b'
`d'
`c'
`a'
onyx:4>
- dstack stack:
Input(s):
None.
Output(s):
stack:
A snapshot of dstack.
Error(s):
None.
Description:
Get a snapshot of dstack.
Example(s):
onyx:0> dstack 1 sprint
(-dict- -dict- -dict- -dict-)
onyx:0>
obj dup obj dup:
Input(s):
obj:
An object.
Output(s):
obj:
The same object that was passed in.
dup:
A duplicate of obj.
Error(s):
stackunderflow.
Description:
Create a duplicate of the top object on ostack. For composite objects, the new object is a reference to the same composite object.
Example(s):
onyx:0> 1 dup pstack
1
1
onyx:2>
obj echeck boolean:
Input(s):
obj:
An object.
Output(s):
boolean:
True if obj has the evaluable attribute, false otherwise.
Error(s):
stackunderflow.
Description:
Check obj for evaluable attribute.
Example(s):
onyx:0> {1 2 3} cve
onyx:1> dup 1 sprint
_{1 2 3}_
onyx:1> echeck 1 sprint
true
onyx:0> {1 2 3} echeck 1 sprint
false
onyx:0> [1 2 3] echeck 1 sprint
false
onyx:0>
- egid gid:
Input(s):
None.
Output(s):
gid:
Process's effective group ID.
Error(s):
None.
Description:
Get the process's effective group ID.
Example(s):
onyx:0> egid 1 sprint
1001
onyx:0>
- end -:
Input(s):
None.
Output(s):
None.
Error(s):
stackunderflow.
Description:
Pop the topmost dictionary off dstack, thereby removing its contents from the namespace.
Example(s):
onyx:0> <$foo `foo'> begin
onyx:0> foo 1 sprint
`foo'
onyx:0> end
onyx:0> foo 1 sprint
Error $undefined
ostack: ()
dstack: (-dict- -dict- -dict- -dict-)
cstack: ()
estack/istack trace (0..2):
0:      foo
1:      -file-
2:      --start--
onyx:1>
- envdict dict:
Input(s):
None.
Output(s):
dict:
A dictionary.
Error(s):
None.
Description:
Get envdict. See Section 2.11.2 for details on envdict.
Example(s):
onyx:0> envdict 0 sprint
-dict-
onyx:0>
arg escape -:
Input(s):
arg:
Argument to be returned by the trapped operator invocation that traps this escape .
Output(s):
None.
Error(s):
stackunderflow.
Description:
Unwind the execution stack to the innermost trapped or start context.
Example(s):
onyx:0> {$arg escape} trapped {1 sprint} if
$arg
onyx:0>
a b eq boolean:
Input(s):
a:
An object.
b:
An object.
Output(s):
boolean:
True if a is equal to b, false otherwise.
Error(s):
stackunderflow.
Description:
Compare two objects for equality. Equality has the following meaning, depending on the types of a and b:
array, condition, dict, file, handle, mutex, stack, thread:
a and b are equal iff they refer to the same memory.
operator:
a and b are equal iff they refer to the same function.
name, string:
a and b are equal iff they are lexically equivalent. A name can be equal to a string.
boolean:
a and b are equal iff they are the same value.
integer, real:
a and b are equal iff they are the same value.
Example(s):
onyx:0> mutex mutex eq 1 sprint
false
onyx:0> mutex dup eq 1 sprint
true
onyx:0> $foo `foo' eq 1 sprint
true
onyx:0> true true eq 1 sprint
true
onyx:0> true false eq 1 sprint
false
onyx:0> 1 1 eq 1 sprint
true
onyx:0> 1 2 eq 1 sprint
false
onyx:0> 1.0 1 eq 1 sprint
true
onyx:0> 1.0 1.1 eq 1 sprint
false
onyx:0>
- estack stack:
Input(s):
None.
Output(s):
stack:
A current snapshot (copy) of the execution stack.
Error(s):
None.
Description:
Get a current snapshot of the execution stack.
Example(s):
onyx:0> estack 1 sprint
(--start-- -file- --estack--)
onyx:0>
- euid uid:
Input(s):
None.
Output(s):
uid:
Process's effective user ID.
Error(s):
None.
Description:
Get the process's effective user ID.
Example(s):
onyx:0> euid 1 sprint
1001
onyx:0>
obj eval -:
Input(s):
obj:
An object.
Output(s):
None.
Error(s):
stackunderflow.
Description:
Evaluate object. See Section 2.1 for details on object evaluation.
Example(s):
onyx:0> ``hi' 1 sprint' cvx eval
`hi'
onyx:0>
a b exch b a:
Input(s):
a:
An object.
b:
An object.
Output(s):
b:
The same object that was passed in.
a:
The same object that was passed in.
Error(s):
stackunderflow.
Description:
Exchange the top two objects on ostack.
Example(s):
onyx:0> 1 2 pstack
2
1
onyx:2> exch pstack
1
2
onyx:2>
args exec -:
Input(s):
args:
An array of strings. The first string in args is the path of the program to invoke, and any additional array elements are passed as command line arguments to the invoked program.
Output(s):
None (this operator does not return).
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Overlay a new program and execute it. The current contents of envdict are used to construct the new program's environment.
Example(s):
onyx:0> `Old program'
onyx:1> [`/usr/local/bin/onyx'] exec
Canonware Onyx, version 1.0.0.
onyx:0>
- exit -:
Input(s):
None.
Output(s):
None.
Error(s):
None.
Description:
Exit the innermost enclosing looping context immediately. This operator can be called within the looping context of for , repeat , while , until , loop , foreach , and dirforeach .
Example(s):
onyx:0> {`hi' 1 sprint exit `bye' 1 sprint} loop
`hi'
onyx:0>
b exp r:
Input(s):
a:
An integer or real.
Output(s):
r:
$e$ raised to the b power.
Error(s):
stackunderflow.
typecheck.
Description:
Return $e$ (the base of natural logarithm) raised to the b power.
Example(s):
onyx:0> 3 exp 1 sprint
2.008554e+01
onyx:0>
- false false:
Input(s):
None.
Output(s):
false:
The boolean value false.
Error(s):
None.
Description:
Return false.
Example(s):
onyx:0> false 1 sprint
false
onyx:0>
obj fcheck boolean:
Input(s):
obj:
An object.
Output(s):
boolean:
True if obj has the fetchable attribute, false otherwise.
Error(s):
stackunderflow.
Description:
Check obj for fetchable attribute.
Example(s):
onyx:0> $name fcheck 1 sprint
false
onyx:0> $name cvf fcheck 1 sprint
true
onyx:0>
a floor r:
Input(s):
a:
An integer or real.
Output(s):
r:
Integer floor of a.
Error(s):
stackunderflow.
typecheck.
Description:
Return the integer floor of a.
Example(s):
onyx:0> -1.51 floor 1 sprint
-2
onyx:0> -1.49 floor 1 sprint
-2
onyx:0> 0 floor 1 sprint
0
onyx:0> 1.49 floor 1 sprint
1
onyx:0> 1.51 floor 1 sprint
1
onyx:0>
- flush -:
Input(s):
None.
Output(s):
None.
Error(s):
ioerror.
Description:
Flush any buffered data associated with stdout.
Example(s):
onyx:0> `Hi\n' print
onyx:0> flush
Hi
onyx:0>
file flushfile -:
Input(s):
file:
A file object.
Output(s):
None.
Error(s):
ioerror.
stackunderflow.
typecheck.
Description:
Flush any buffered data associated with file.
Example(s):
onyx:0> `Hi\n' print
onyx:0> stdout flushfile
Hi
onyx:0>
init inc limit proc for -:
Input(s):
init:
Initial value of control variable.
inc:
Amount to increment control variable by at the end of each iteration.
limit:
Inclusive upper bound for control variable if less than or equal to init, otherwise inclusive lower bound for control variable.
proc:
An object.
Output(s):
At the beginning of each iteration, the current value of the control variable is pushed onto ostack.
Error(s):
stackunderflow.
typecheck.
Description:
Iteratively evaluate proc, pushing a control variable onto ostack at the beginning of each iteration, until the control variable has exceeded limit. This operator supports the continue and exit operators.
Example(s):
onyx:0> 0 1 3 {1 sprint} for
0
1
2
3
onyx:0> 0 -1 -3 {1 sprint} for
0
-1
-2
-3
onyx:0> 0 2 7 {1 sprint} for
0
2
4
6
onyx:0> 0 1 1000 {dup 1 sprint 3 eq {exit} if} for
0
1
2
3
onyx:0>
array proc foreach -:
dict proc foreach -:
stack proc foreach -:
string proc foreach -:
Input(s):
array:
An array object.
dict:
A dict object.
stack:
A stack object.
string:
A string object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
For each entry in the first input argument (array, dict, stack, or string), push the entry onto ostack and execute proc. This operator supports the continue and exit operators.

The object being iterated over can be modified during iteration, with the expectation of no ill consequences, and in most cases the modifications are immediately apparent. However, there are some cases in which behavior does not follow this guideline:

 $$
Objects inserted into a dictionary during iteration may or may not be iterated over.
 $$
In the case of stack iteration, a snapshot is taken before iteration begins, so any changes to the stack during iteration will not affect iteration in any way.
Example(s):
onyx:0> [1 2] {1 sprint} foreach
1
2
onyx:0> <$foo `foo' $bar `bar'> {pstack clear} foreach
`bar'
$bar
`foo'
$foo
onyx:0> (1 2) {pstack clear} foreach
2
1
onyx:0> `ab' {pstack clear} foreach
97
98
onyx:0>
args forkexec pid:
args redirects forkexec pid:
Input(s):
args:
An array of strings. The first string in args is the path of the program to invoke, and any additional array elements are passed as command line arguments to the invoked program.
redirects:
A dictionary of file redirections. Each key/value pair specifies that the file descriptor associated with the key should be replaced by the file descriptor associated with the value. The file descriptor associated with the key is kept open across the exec.
Output(s):
pid:
Process identifier for the new process, or 0 if the child process.
Error(s):
argcheck.
limitcheck.
rangecheck.
stackunderflow.
typecheck.
Description:
Fork and exec a new process. The current contents of envdict are used to construct the new program's environment.
Example(s):
onyx:0> [`/bin/date'] forkexec dup 1 sprint waitpid 1 sprint
6516
Sat Jul 13 20:47:54 PDT 2002
0
onyx:0>
- gcdict dict:
Input(s):
None.
Output(s):
dict:
A dictionary.
Error(s):
None.
Description:
Get gcdict. See Section 2.11.4 for details on gcdict.
Example(s):
onyx:0> gcdict 0 sprint
-dict-
onyx:0>
a b ge boolean:
Input(s):
a:
A number (integer or real) or string.
b:
An object of a type compatible with a.
Output(s):
boolean:
True if a is greater than or equal to b, false otherwise.
Error(s):
stackunderflow.
typecheck.
Description:
Compare two numbers or strings.
Example(s):
onyx:0> 1 2 ge 1 sprint
false
onyx:0> 1 1 ge 1 sprint
true
onyx:0> 2 1 ge 1 sprint
true
onyx:0> 1 1.1 ge 1 sprint
false
onyx:0> 1.1 1.1 ge 1 sprint
true
onyx:0> 1.1 1 ge 1 sprint
true
onyx:0> `a' `b' ge 1 sprint
false
onyx:0> `a' `a' ge 1 sprint
true
onyx:0> `b' `a' ge 1 sprint
true
onyx:0>
array index get obj:
dict key get value:
string index get integer:
Input(s):
array:
An array object.
dict:
A dict object.
string:
A string object.
index:
Offset of array element or string element.
key:
A key in dict.
Output(s):
obj:
The object in array at offset index.
value:
The value in dict corresponding to key.
integer:
The ascii value of the character in string at offset index.
Error(s):
rangecheck.
stackunderflow.
typecheck.
undefined.
Description:
Get an element of array, a value in dict, or an element of string.
Example(s):
onyx:0> [`a' `b' `c'] 1 get 1 sprint
`b'
onyx:0> <$foo `foo' $bar `bar'> $bar get 1 sprint
`bar'
onyx:0> `abc' 1 get 1 sprint
98
onyx:0>
array index length getinterval subarray:
string index length getinterval substring:
Input(s):
array:
An array object.
string:
A string object.
index:
The offset into array or string to get the interval from.
length:
The length of the interval in array or string to get.
Output(s):
subarray:
A subarray of array at offset index and of length length.
substring:
A substring of string at offset index and of length length.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Get an interval of array or string.
Example(s):
onyx:0> [0 1 2 3] 1 2 getinterval 1 sprint
[1 2]
onyx:0> `abcd' 1 2 getinterval 1 sprint
`bc'
onyx:0>
pid getpgid pgid:
Input(s):
pid:
Process ID, or 0 (same as specifying the calling process's ID).
Output(s):
pgid:
Process group ID.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Get the process group ID for the process with ID pid.
Example(s):
onyx:0> 0 getpgid 1 sprint
15864
onyx:0>
pid getsid sid:
Input(s):
pid:
Process ID, or 0 (same as specifying the calling process's ID).
Output(s):
sid:
Session ID.
Error(s):
stackunderflow.
typecheck.
Description:
Get the session ID for the process with ID pid.
Example(s):
onyx:0> 0 getsid 1 sprint
1120
onyx:0>
- gid gid:
Input(s):
None.
Output(s):
gid:
Process's group ID.
Error(s):
None.
Description:
Get the process's group ID.
Example(s):
onyx:0> gid 1 sprint
1001
onyx:0>
- globaldict dict:
Input(s):
None.
Output(s):
dict:
A dictionary.
Error(s):
None.
Description:
Get globaldict. See Section 2.11.5 for details on globaldict.
Example(s):
onyx:0> globaldict 1 sprint
<>
onyx:0>
- gmaxestack count:
Input(s):
None.
Output(s):
count:
Default maximum allowable estack depth.
Error(s):
None.
Description:
Get the default maximum allowable estack depth. This value is used when creating new threads.
Example(s):
onyx:0> gmaxestack 1 sprint
256
onyx:0>
- gstderr file:
Input(s):
None.
Output(s):
file:
A file object corresponding to the global stderr.
Error(s):
None.
Description:
Get the global stderr that is inherited by new threads. See Section 2.4 for standard I/O details.
Example(s):
onyx:0> gstderr pstack
-file-
onyx:1>
- gstdin file:
Input(s):
None.
Output(s):
file:
A file object corresponding to the global stdin.
Error(s):
None.
Description:
Get the global stdin that is inherited by new threads. See Section 2.4 for standard I/O details.
Example(s):
onyx:0> gstdin pstack
-file-
onyx:1>
- gstdout file:
Input(s):
None.
Output(s):
file:
A file object corresponding to the global stdout.
Error(s):
None.
Description:
Get the global stdout that is inherited by new threads. See Section 2.4 for standard I/O details.
Example(s):
onyx:0> gstdout pstack
-file-
onyx:1>
a b gt boolean:
Input(s):
a:
A number (integer or real) or string.
b:
An object of a type compatible with a.
Output(s):
boolean:
True if a is greater than b, false otherwise.
Error(s):
stackunderflow.
typecheck.
Description:
Compare two numbers or strings.
Example(s):
onyx:0> 1 1 gt 1 sprint
false
onyx:0> 2 1 gt 1 sprint
true
onyx:0> 1.1 1.1 gt 1 sprint
false
onyx:0> 1.1 1 gt 1 sprint
true
onyx:0> `a' `a' gt 1 sprint
false
onyx:0> `b' `a' gt 1 sprint
true
onyx:0>
- gtailopt boolean:
Input(s):
None.
Output(s):
boolean:
True if tail call optimization is enabled by default for new threads, false otherwise.
Error(s):
None.
Description:
Get whether tail call optimization is enabled by default for new threads.
Example(s):
onyx:0> gtailopt 1 sprint
true
onyx:0>
handle handletag tag:
Input(s):
handle:
A handle object.
Output(s):
tag:
The tag associated with handle.
Error(s):
stackunderflow.
typecheck.
Description:
Get the tag associated with handle.

...obj ,,,index ibdup ...obj ,,,dup:
Input(s):
...:
index objects.
obj:
An object.
,,,:
Zero or more objects.
index:
Offset from bottom of ostack, counting from 0.
Output(s):
...:
index objects.
obj:
An object.
,,,:
Zero or more objects.
dup:
Duplicate of obj.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Create a duplicate of the object on ostack that is at offset index from the bottom of ostack.
Example(s):
onyx:4> 2 ibdup pstack
2
3
2
1
0
onyx:5>
...obj ,,,index ibpop ...,,,:
Input(s):
...:
index objects.
obj:
An object.
,,,:
Zero or more objects.
index:
Offset from bottom of ostack, counting from 0.
Output(s):
...:
index objects.
,,,:
Zero or more objects.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Remove the object from ostack that is at offset index from the bottom of ostack.
Example(s):
onyx:0> 0 1 2 3
onyx:4> 2 ibpop pstack
3
1
0
onyx:3>
obj icheck boolean:
Input(s):
obj:
An object.
Output(s):
boolean:
True if obj has the invokable attribute, false otherwise.
Error(s):
stackunderflow.
Description:
Check obj for invokable attribute.
Example(s):
onyx:0> $name icheck 1 sprint
false
onyx:0> $name cvi icheck 1 sprint
true
onyx:0>
a b idiv r:
Input(s):
a:
An integer.
b:
A non-zero integer.
Output(s):
r:
The integer quotient of a divided by b.
Error(s):
stackunderflow.
typecheck.
undefinedresult.
Description:
Return the integer quotient of a divided by b.
Example(s):
onyx:0> 4 2 idiv 1 sprint
2
onyx:0> 5 2 idiv 1 sprint
2
onyx:0> 5 0 idiv
Error $undefinedresult
ostack: (5 0)
dstack: (-dict- -dict- -dict- -dict-)
cstack: ()
estack/istack trace (0..2):
0:      --idiv--
1:      -file-
2:      --start--
onyx:3>
obj ...index idup obj ...dup:
Input(s):
obj:
An object.
index:
Offset from top of ostack, counting from 0, not counting index), of the object to duplicate on ostack.
Output(s):
obj:
The same object that was passed in.
dup:
A duplicate of obj.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Create a duplicate of the object on ostack at index.
Example(s):
onyx:0> 3 2 1 0 2 idup pstack
2
0
1
2
3
onyx:5>
boolean obj if -:
Input(s):
boolean:
A boolean.
obj:
An object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Evaluate obj if boolean is true.
Example(s):
onyx:0> true {`yes' 1 sprint} if
`yes'
onyx:0> false {`yes' 1 sprint} if
onyx:0>
boolean a b ifelse -:
Input(s):
boolean:
A boolean.
a:
An object.
b:
An object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Evaluate a if boolean is true, evaluate b otherwise. See Section 2.1 for details on object evaluation.
Example(s):
onyx:0> true {`yes'}{`no'} ifelse 1 sprint
`yes'
onyx:0> false {`yes'}{`no'} ifelse 1 sprint
`no'
onyx:0>
obj ilocked boolean:
Input(s):
obj:
An array, dict, file, or string.
Output(s):
boolean:
True if obj is implicitly locked, false otherwise.
Error(s):
stackunderflow.
typecheck.
Description:
Check if obj is implicitly locked.
Example(s):
onyx:0> false setlocking
onyx:0> [1 2 3] ilocked 1 sprint
false
onyx:0> true setlocking
onyx:0> [1 2 3] ilocked 1 sprint
true
onyx:0>
class name implementor class/null:
Input(s):
class:
A class object.
name:
An object of any type, usually a name object.
Output(s):
class/null:
A class or null object.
Error(s):
stackunderflow.
typecheck.
Description:
Search up class's inheritance hierarchy and return the first class that implements name, or a null object if name is not implemented.
Example(s):
onyx:0> class dup vclass setsuper
onyx:1> $new implementor classname 1 sprint
$vclass
onyx:0>
class name implements boolean:
Input(s):
class:
A class object.
name:
An object of any type, usually a name object.
Output(s):
boolean:
True if name is implemented by class, false otherwise.
Error(s):
stackunderflow.
typecheck.
Description:
Return true if name is implemented by class; return false otherwise.
Example(s):
onyx:1> vclass $new implements 1 sprint
true
onyx:1> vclass $foo implements 1 sprint
false
onyx:1>
a inc r:
Input(s):
a:
An integer.
Output(s):
r:
$a + 1$.
Error(s):
stackunderflow.
typecheck.
Description:
Add one to a.
Example(s):
onyx:0> 1 inc 1 sprint
2
onyx:0>
- instance instance:
Input(s):
None.
Output(s):
instance:
Error(s):
None.
Description:
Create an instance object.
Example(s):
onyx:0> instance 1 sprint
-instance-
onyx:0>
file iobuf count:
Input(s):
file:
A file object.
Output(s):
count:
The size in bytes of the I/O buffer associated with file.
Error(s):
stackunderflow.
typecheck.
Description:
Get the size of the I/O buffer associated with file.
Example(s):
onyx:0> stdout iobuf 1 sprint
512
onyx:0> stderr iobuf 1 sprint
0
onyx:0>
obj ...index ipop ...:
Input(s):
obj:
An object.
index:
Offset from top of ostack, counting from 0, not counting index), of the object to remove from ostack.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Remove the obj at index from ostack.
Example(s):
onyx:0> 2 1 0
onyx:3> 1 ipop pstack
0
2
onyx:2>
instance isa class/null:
Input(s):
instance:
An instance object.
Output(s):
class/null:
A class or null object.
Error(s):
stackunderflow.
typecheck.
Description:
Get the class object that instance is an instance of.
Example(s):
onyx:0> instance isa 1 sprint
null
onyx:0> instance dup vclass setisa
onyx:1> isa classname 1 sprint
$vclass
onyx:0>
- istack stack:
Input(s):
None.
Output(s):
stack:
A current snapshot (copy) of the index stack.
Error(s):
None.
Description:
Get a current snapshot of the index stack.
Example(s):
onyx:0> istack 1 sprint
(0 0 0)
onyx:0>
thread join -:
Input(s):
thread:
A thread object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Wait for thread to exit. A thread may only be detached or joined once; any attempt to do so more than once results in undefined behavior (likely crash).
Example(s):
onyx:0> (1 2) {add 1 sprint} thread join `Done\n' print flush
3
Done
onyx:0>
pid sig kill -:
Input(s):
pid:
An integer. If pid is greater than 0, it specifies a process ID. If pid is 0, it specifies the calling program's process group. If pid is -1, the signal is sent to all non-system processes with ID 1. If pid is less than -1, its absolute value specifies a process group.
sig:
An integer, or one of the following names:
  • $SIGABRT
  • $SIGALRM
  • $SIGBUS
  • $SIGCHLD
  • $SIGCONT
  • $SIGFPE
  • $SIGHUP
  • $SIGILL
  • $SIGINT
  • $SIGKILL
  • $SIGPIPE
  • $SIGQUIT
  • $SIGSEGV
  • $SIGSTOP
  • $SIGTERM
  • $SIGTSTP
  • $SIGTTIN
  • $SIGTTOU
  • $SIGUSR1
  • $SIGUSR2
  • $SIGPOLL (may not be present)
  • $SIGPROF
  • $SIGSYS
  • $SIGTRAP
  • $SIGURG
  • $SIGVTALRM (may not be present)
  • $SIGXCPU
  • $SIGXFSZ
Output(s):
None.
Error(s):
argcheck.
invalidaccess.
limitcheck.
rangecheck.
stackunderflow.
typecheck.
unregistered.
Description:
Send the signal specified by sig to the process or process group specified by pid.
Example(s):
onyx:0> pid $SIGCONT kill
onyx:0>
instance class kind boolean:
Input(s):
instance:
An instance object.
class:
A class object.
Output(s):
boolean:
True if class is in instance's inheritance hierarchy, false otherwise.
Error(s):
stackunderflow.
typecheck.
Description:
Determine whether class is in instance's inheritance hierarchy.
Example(s):
onyx:0> $fooclass class dup vclass setsuper def
onyx:0> instance dup fooclass setisa
onyx:1> dup fooclass kind 1 sprint
true
onyx:1> dup vclass kind 1 sprint
true
onyx:1>
dict key known boolean:
Input(s):
dict:
A dictionary.
key:
A key to look for in dict.
Output(s):
boolean:
True if key is defined in dict, false otherwise.
Error(s):
stackunderflow.
typecheck.
Description:
Check whether key is defined in dict.
Example(s):
onyx:1> <$foo `foo'> $foo known 1 sprint
true
onyx:1> <$foo `foo'> $bar known 1 sprint
false
onyx:1>
obj lcheck boolean:
Input(s):
obj:
An object.
Output(s):
boolean:
True if obj has the literal attribute, false otherwise.
Error(s):
stackunderflow.
Description:
Check obj for literal attribute.
Example(s):
onyx:0> {1 2 3} lcheck 1 sprint
false
onyx:0> [1 2 3] lcheck 1 sprint
true
onyx:0>
a b le boolean:
Input(s):
a:
A number (integer or real) or string.
b:
An object of a type compatible with a.
Output(s):
boolean:
True if a is less than or equal to b, false otherwise.
Error(s):
stackunderflow.
typecheck.
Description:
Compare two numbers or strings.
Example(s):
onyx:0> 1 2 le 1 sprint
true
onyx:0> 1 1 le 1 sprint
true
onyx:0> 2 1 le 1 sprint
false
onyx:0> 1 1.1 le 1 sprint
true
onyx:0> 1.1 1.1 le 1 sprint
true
onyx:0> 1.1 1 le 1 sprint
false
onyx:0> `a' `b' le 1 sprint
true
onyx:0> `a' `a' le 1 sprint
true
onyx:0> `b' `a' le 1 sprint
false
onyx:0>
array length count:
dict length count:
name length count:
string length count:
Input(s):
array:
An array object.
dict:
A dict object.
name:
A name object.
string:
A string object.
Output(s):
count:
Number of elements in array, number of entries in dict, number of characters in name, or number of characters in string.
Error(s):
stackunderflow.
typecheck.
Description:
Get the umber of elements in array, number of entries in dict, number of characters in name, or number of characters in string.
Example(s):
onyx:0> [1 2 3] length 1 sprint
3
onyx:0> <$foo `foo' $bar `bar'> length 1 sprint
2
onyx:0> $foo length 1 sprint
3
onyx:0> `foo' length 1 sprint
3
onyx:0>
filename linkname link -:
Input(s):
filename:
A string that represents a filename.
linkname:
A string that represents a filename.
Output(s):
None.
Error(s):
invalidfileaccess.
ioerror.
stackunderflow.
typecheck.
undefinedfilename.
unregistered.
Description:
Create a hard link from linkname to filename.
Example(s):
onyx:0> `/tmp/foo' `w' open
onyx:1> dup `Hello\n' write
onyx:1> dup flushfile
onyx:1> close
onyx:0> `/tmp/foo' `/tmp/bar' link
onyx:0> `/tmp/bar' `r' open
onyx:1> readline
onyx:2> pstack
false
`Hello'
onyx:2>
sock backlog listen -:
sock listen -:
Input(s):
sock:
A socket.
backlog:
Maximum backlog of connections to listen for. If not specified, the maximum backlog is used.
Output(s):
None.
Error(s):
invalidfileaccess.
neterror.
rangecheck.
stackunderflow.
typecheck.
unregistered.
Description:
Listen for connections on a socket.
Example(s):
onyx:0> $AF_INET $SOCK_STREAM socket
onyx:1> dup `localhost' 7777 bindsocket
onyx:1> dup listen
onyx:1>
a ln r:
Input(s):
a:
An integer or real.
Output(s):
r:
Natural logarithm of a.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Return the natural logarithm of a.
Example(s):
onyx:0> 5 ln 1 sprint
1.609438e+00
onyx:0> 8.5 ln 1 sprint
2.140066e+00
onyx:0>
key load val:
Input(s):
key:
A key to look up in dstack.
Output(s):
val:
The value associated with the topmost definition of key in dstack.
Error(s):
stackunderflow.
undefined.
Description:
Get the topmost definition of key in dstack.
Example(s):
onyx:1> <$foo `foo'> begin
onyx:1> <$foo `FOO'> begin
onyx:1> $foo load 1 sprint
`FOO'
onyx:1>
nsecs localtime dict:
Input(s):
nsecs:
Number of nanoseconds since the epoch.
Output(s):
dict:
A dictionary that contains the following entries:
sec:
Seconds (0-59).
min:
Minutes (0-59).
hour:
Hours (0-23).
mday:
Month day (1-31).
mon:
Month (0-11).
year:
Year.
wday:
Week day (0-6, Sunday is 0).
yday:
Year day (0-365).
isdst:
Is daylight savings time (true or false).
zone:
Time zone (string).
gmtoff:
Offset from UTC in seconds.
Error(s):
stackunderflow.
rangecheck.
typecheck.
Description:
Convert a time, as returned by realtime, to a dictionary that contains time information in a more human-usable format.
Example(s):
onyx:0> $date {
    realtime localtime

    [`Sunday' `Monday' `Tuesday' `Wednesday' `Thursday' `Friday' `Saturday']
    over $wday get
    get
    ` ' cat

    over $year get cvs
    `/' 3 ncat

    over $mon get inc <$w 2 $p `0'> outputs
    `/' 3 ncat

    over $mday get <$w 2 $p `0'> outputs
    ` ' 3 ncat

    over $hour get <$w 2 $p `0'> outputs
    `:' 3 ncat

    over $min get <$w 2 $p `0'> outputs
    `:' 3 ncat

    over $sec get <$w 2 $p `0'> outputs
    ` (' 3 ncat

    exch $zone get
    `)\n' 3 ncat

    print flush
} def
onyx:0> date
Monday 2003/03/17 01:31:49 (PST)
onyx:0>
mutex lock -:
Input(s):
mutex:
A mutex object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Acquire mutex, waiting if necessary. Attempting to acquire mutex recursively will result in undefined behavior (likely deadlock or crash).
Example(s):
onyx:0> mutex dup lock unlock
onyx:0>
a log r:
Input(s):
a:
An integer or real.
Output(s):
r:
Base 10 logarithm of a.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Return the base 10 logarithm of a.
Example(s):
onyx:0> 5 log 1 sprint
6.989700e-01
onyx:0> 8.5 log 1 sprint
9.294189e-01
onyx:0>
proc loop -:
Input(s):
proc:
An object to evaluate.
Output(s):
None.
Error(s):
stackunderflow.
Description:
Repeatedly evaluate proc indefinitely. This operator supports the continue and exit operators.
Example(s):
onyx:0> 0 {1 add dup 1 sprint dup 3 eq {pop exit} if} loop
1
2
3
onyx:0>
a b lt boolean:
Input(s):
a:
A number (integer or real) or string.
b:
An object of a type compatible with a.
Output(s):
boolean:
True if a is less than b, false otherwise.
Error(s):
stackunderflow.
typecheck.
Description:
Compare two numbers or strings.
Example(s):
onyx:0> 1 2 lt 1 sprint
true
onyx:0> 1 1 lt 1 sprint
false
onyx:0> 1 1.1 lt 1 sprint
true
onyx:0> 1.1 1.1 lt 1 sprint
false
onyx:0> 1.1 1 lt 1 sprint
false
onyx:0> `a' `b' lt 1 sprint
true
onyx:0> `a' `a' lt 1 sprint
false
onyx:0>
- mark mark:
Input(s):
None.
Output(s):
mark:
A mark object.
Error(s):
None.
Description:
Push a mark onto ostack.
Example(s):
onyx:0> mark pstack
-mark-
onyx:1>
- maxestack count:
Input(s):
None.
Output(s):
count:
Maximum allowable estack depth.
Error(s):
None.
Description:
Get the maximum allowable estack depth.
Example(s):
onyx:0> maxestack 1 sprint
256
onyx:0>
input pattern flags match boolean:
input pattern match boolean:
input regex match boolean:
Input(s):
input:
An input string to find matches in.
pattern:
A string that specifies a regular expression. See Section 2.9 for syntax.
flags:
A dictionary of optional flags:
$c:
Continue where previous match ended. Don't update the offset to start the next match from unless this match is successful. Defaults to false.
$g:
Continue where previous match ended. If the match is unsuccessful, update the offset to start the next match from to the beginning of input. Defaults to false.
$i:
Case insensitive. Defaults to false.
$m:
Treat input as a multi-line string. Defaults to false.
$s:
Treat input as a single line, so that the dot metacharacter matches any character, including a newline. Defaults to false.
regex:
A regex object.
Output(s):
boolean:
true:
Match successful.
false:
No match found.
Error(s):
regexerror.
stackunderflow.
typecheck.
Description:
Look in input for a match to the regular expression specified by regex/pattern/flags.
Example(s):
onyx:0> `input' `I' <$i true> match {0 submatch 1 sprint} if
`i'
onyx:0> `input' `I' <$i true> regex match {0 submatch 1 sprint} if
`i'
onyx:0> `input' `I' match {0 submatch 1 sprint} if
onyx:0>
class name method method:
Input(s):
class:
A class object.
name:
An object of any type, usually a name object.
Output(s):
method:
The bottommost method associated with name in class's inheritance hierarchy.
Error(s):
stackunderflow.
typecheck.
undefined.
Description:
Get the bottommost method associated with name in class's inheritance hierarchy.
Example(s):
onyx:0> $fooclass class dup vclass setsuper def
onyx:0> fooclass $new method 1 sprint
{--instance-- --dup-- --dn-- --setisa-- --dup-- --dict-- --setdata--}
onyx:0>
class methods dict/null:
Input(s):
class:
A class object.
Output(s):
dict/null:
A dict or null object.
Error(s):
stackunderflow.
typecheck.
Description:
Get the methods associated with class.
Example(s):
onyx:0> vclass methods 0 sprint
-dict-
onyx:0>
path mkdir -:
path mode mkdir -:
Input(s):
path:
A string object that represents a directory path.
mode:
An integer that represents a Unix file mode.
Output(s):
None.
Error(s):
invalidfileaccess.
ioerror.
rangecheck.
stackunderflow.
typecheck.
unregistered.
Description:
Create a directory.
Example(s):
onyx:0> `/tmp/tdir' 8@755 mkdir
onyx:0> `/tmp/tdir' {1 sprint} dirforeach
`.'
`..'
onyx:0>
path mkfifo -:
path mode mkfifo -:
Input(s):
path:
A string object that represents a directory path.
mode:
An integer that represents a Unix file mode.
Output(s):
None.
Error(s):
invalidfileaccess.
ioerror.
rangecheck.
stackunderflow.
typecheck.
unregistered.
Description:
Create a named pipe.
Example(s):
onyx:0> `/tmp/fifo' mkfifo
onyx:0>
a b mod r:
Input(s):
a:
An integer or real.
b:
A non-zero integer or real.
Output(s):
r:
The modulus of a and b.
Error(s):
stackunderflow.
typecheck.
undefinedresult.
Description:
Return the modulus of a and b. Note that a and b can be any combination of integers and reals.
Example(s):
onyx:0> 4 2 mod 1 sprint
0
onyx:0> 5 2 mod 1 sprint
1
onyx:0> 5 0 mod
Error $undefinedresult
ostack: (5 0)
dstack: (-dict- -dict- -dict- -dict-)
cstack: ()
estack/istack trace (0..2):
0:      --mod--
1:      -file-
2:      --start--
onyx:3>
path symbol modload -:
Input(s):
path:
A string that represents a module filename.
symbol:
A string that represents the symbol name of a module initialization function to be executed.
Output(s):
None.
Error(s):
invalidfileaccess.
stackunderflow.
typecheck.
undefined.
Description:
Dynamically load a module, create a handle object that encapsulates the handle returned by dlopen(3) (handle data pointer) and the module initialization function (handle evaluation function), and evaluate the handle.

All objects that refer to code and/or data that are part of the module must directly and/or indirectly maintain a reference to the handle that is evaluated by this operator, since failing to do so would allow the garbage collector to unload the module, which could result in dangling pointers to unmapped memory regions.

Loadable modules present a problem for the garbage collector during the sweep phase. All objects that refer to memory that is dynamically mapped as part of the module must be destroyed before the module is unloaded. Destruction ordering constraints show up in other situations as well, but in the case of loadable modules, there is no reasonable solution except to explicitly order the destruction of objects. Therefore, by default, the handle that is evaluated by modload is destroyed during the second sweep pass (count starts at 0). It is possible for a module to override what sweep pass the handle is destroyed on, in cases where there are additional ordering constraints for the objects created by a module. This isn't important from the Onyx language perspective, but is important to understand when implementing modules.

Example(s):
onyx:0> `/usr/local/share/onyx/nxm/modprompt.nxm' `modprompt_init'
onyx:2> modload
onyx:0>
mutex proc monitor -:
Input(s):
mutex:
A mutex.
proc:
Any object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Execute proc while holding mutex.
Example(s):
onyx:0> mutex {`hello\n' print} monitor flush
hello
onyx:0>
file symbol mrequire -:
Input(s):
file:
A string that represents a module filename.
symbol:
A string that represents the symbol name of a module initialization function to be executed.
Output(s):
None.
Error(s):
invalidfileaccess.
stackunderflow.
typecheck.
undefined.
undefinedfilename.
Description:
Search for and load a module. The module is searched for by catenating a prefix, a ``/'', and file to form a file path. Prefixes are tried in the following order:
  1. The ordered elements of the mpath_pre array, which is defined in onyxdict.
  2. If defined, the ordered elements of the ONYX_MPATH environment variable, which is a colon-separated list.
  3. The ordered elements of the mpath_post array, which is defined in onyxdict.
Example(s):
onyx:0> `modgtk.nxm' `modgtk_init' mrequire
onyx:0>
a b mul r:
Input(s):
a:
An integer or real.
b:
An integer or real.
Output(s):
r:
The product of a and b.
Error(s):
stackunderflow.
typecheck.
Description:
Return the product of a and b.
Example(s):
onyx:0> 3 17 mul 1 sprint
51
onyx:0> -5 -6 mul 1 sprint
30
onyx:0> 3.5 4.0 mul 1 sprint
1.400000e+01
onyx:0> -1.5 3 mul 1 sprint
-4.500000e+00
onyx:0>
- mutex mutex:
Input(s):
None.
Output(s):
mutex:
A mutex object.
Error(s):
None.
Description:
Create a mutex.
Example(s):
onyx:0> mutex 1 sprint
-mutex-
onyx:0>
objects ...count nbpop ...:
Input(s):
objects:
Zero or more objects.
count:
Number of objects to pop.
Output(s):
None.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Remove the bottom count objects from ostack and discard them.
Example(s):
onyx:0> `a' `b' `c' 2 nbpop pstack
`c'
onyx:1>
arrays count ncat array:
stacks count ncat stack:
strings count ncat string:
Input(s):
arrays:
count arrays.
stacks:
count stacks.
strings:
count strings.
count:
Number of arrays, stacks, or strings to catenate.
Output(s):
obj:
The catenation of arrays, stacks, or strings.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Catenate count arrays, stacks, or strings.
Example(s):
onyx:0> [`a'] [`b'] [`c'] 3 ncat 1 sprint
[`a' `b' `c']
onyx:0> (`a') (`b') (`c') 3 ncat 1 sprint
(`a' `b' `c')
onyx:0> `a' `b' `c' 3 ncat 1 sprint
`abc'
onyx:0>
a ...b count ndn ...b a:
Input(s):
a:
An object.
...:
$count - 2$ objects.
b:
An object.
count:
Number of objects to rotate downward.
Output(s):
...:
$count - 2$ objects.
b:
An object.
a:
An object.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Rotate count objects on ostack down one position.
Example(s):
onyx:0> `a' `b' `c' `d' `e' 4 ndn pstack
`b'
`e'
`d'
`c'
`a'
onyx:5>
objects count ndup objects objects:
Input(s):
objects:
Zero or more objects.
count:
The number of objects do duplicate.
Output(s):
objects:
The same objects that were passed in.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Create duplicates of the top count objects on ostack. For composite objects, the new object is a reference to the same composite object.
Example(s):
onyx:0> `a' `b' `c' 2 ndup pstack
`c'
`b'
`c'
`b'
`a'
onyx:5>
a b ne boolean:
Input(s):
a:
An object.
b:
An object.
Output(s):
boolean:
True if a is not equal to b, false otherwise.
Error(s):
stackunderflow.
Description:
Compare two objects for inequality. Inequality has the following meaning, depending on the types of a and b:
array, condition, dict, file, handle, mutex, stack, thread:
a and b are not equal unless they refer to the same memory.
operator:
a and b are not equal unless they refer to the same function.
name, string:
a and b are not equal iff they are lexically equivalent. A name can be equal to a string.
boolean:
a and b are not equal unless they are the same value.
integer, real:
a and b are not equal unless they are the same value.
Example(s):
onyx:0> mutex mutex ne 1 sprint
true
onyx:0> mutex dup ne 1 sprint
false
onyx:0> $foo `foo' ne 1 sprint
false
onyx:0> $foo $bar ne 1 sprint
true
onyx:0> true false ne 1 sprint
true
onyx:0> true true ne 1 sprint
false
onyx:0> 1 1 ne 1 sprint
false
onyx:0> 1 2 ne 1 sprint
true
onyx:0> 1.0 1 ne 1 sprint
false
onyx:0> 1.0 1.1 ne 1 sprint
true
onyx:0>
a neg r:
Input(s):
a:
An integer.
Output(s):
r:
The negative of a.
Error(s):
stackunderflow.
typecheck.
Description:
Return the negative of a.
Example(s):
onyx:0> 0 neg 1 sprint
0
onyx:0> 5 neg 1 sprint
-5
onyx:0> -5 neg 1 sprint
5
onyx:0> 3.14 neg 1 sprint
-3.140000e+00
onyx:0> -3.14 neg 1 sprint
3.140000e+00
onyx:0>
a b nip b:
Input(s):
a:
An object.
b:
An object.
Output(s):
b:
An object.
Error(s):
stackunderflow.
Description:
Remove the second to top object from ostack.
Example(s):
onyx:0> `a' `b' `c'
onyx:3> nip pstack
`c'
`a'
onyx:2>
file nonblocking boolean:
Input(s):
file:
A file object.
Output(s):
boolean:
Nonb-blocking mode for file.
Error(s):
stackunderflow.
typecheck.
Description:
Get non-blocking mode for file.
Example(s):
onyx:0> `/tmp/foo' `w' open
onyx:1> dup nonblocking 1 sprint
false
onyx:1> dup true setnonblocking
onyx:1> dup nonblocking 1 sprint
true
onyx:1>
a not r:
Input(s):
a:
An integer or boolean.
Output(s):
r:
If a is an integer, the bitwise negation of a, otherwise the logical negation of a.
Error(s):
stackunderflow.
typecheck.
Description:
Return the bitwise negation of an integer, or the logical negation of a boolean.
Example(s):
onyx:0> true not 1 sprint
false
onyx:0> false not 1 sprint
true
onyx:0> 1 not 1 sprint
-2
onyx:0>
objects count npop -:
Input(s):
objects:
Zero or more objects.
count:
Number of objects to pop.
Output(s):
None.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Remove the top count objects from ostack and discard them.
Example(s):
onyx:0> `a' `b' `c' 2 npop pstack
`a'
onyx:1>
nanoseconds nsleep -:
Input(s):
nanoseconds:
Minimum number of nanoseconds to sleep. Must be greater than 0.
Output(s):
None.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Sleep for at least nanoseconds nanonseconds.
Example(s):
onyx:0> 1000 nsleep
onyx:0>
- null null:
Input(s):
None.
Output(s):
null:
A null object.
Error(s):
None.
Description:
Create a null object.
Example(s):
onyx:0> null pstack
null
onyx:1>
a ...b count nup b a ...:
Input(s):
a:
An object.
...:
$count - 2$ objects.
b:
An object.
count:
Number of objects to rotate upward.
Output(s):
b:
An object.
a:
An object.
...:
$count - 2$ objects.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Rotate count objects on ostack up one position.
Example(s):
onyx:0> `a' `b' `c' `d' `e' 4 nup pstack
`d'
`c'
`b'
`e'
`a'
onyx:5>
input submatch offset offset:
Input(s):
input:
A string.
submatch:
A substring of input.
Output(s):
offset:
The integer offset of submatch, relative to the beginning of input.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Get the offset of submatch, relative to the beginning of input. submatch must be a substring of input.
Example(s):
onyx:0> `input' dup `n(p)u' match {1 submatch offset 1 sprint} if
2
onyx:0>
- onyxdict dict:
Input(s):
None.
Output(s):
dict:
A dictionary.
Error(s):
None.
Description:
Get onyxdict. See Section 2.11.6 for details on onyxdict.
Example(s):
onyx:0> onyxdict 1 sprint
<$rpath_pre -array- $rpath_post -array- $mpath_pre -array- $mpath_post -array->
onyx:0>
filename flags open file:
filename flags mode open file:
Input(s):
filename:
A string that represents a filename.
flags:
A string that represents a file mode:
`r':
Read only.
`r+':
Read/write, starting at offset 0.
`w':
Write only. Create file if necessary. Truncate file if non-zero length.
`w+':
Read/write, starting at offset 0. Create file if necessary.
`a':
Write only, starting at end of file.
`a+':
Read/write, starting at end of file.
mode:
Mode to use when creating a new file (defaults to 0777). Note that the process's umask also affects creation mode.
Output(s):
file:
A file object.
Error(s):
invalidfileaccess.
ioerror.
limitcheck.
rangecheck.
stackunderflow.
typecheck.
Description:
Open a file.
Example(s):
onyx:0> `/tmp/foo' `w' open pstack
-file-
onyx:1>
a b or r:
Input(s):
a:
An integer or boolean.
b:
The same type as a.
Output(s):
r:
If a and b are integers, their bitwise or, otherwise their logical or.
Error(s):
stackunderflow.
typecheck.
Description:
Return the bitwise or of two integers, or the logical or of two booleans.
Example(s):
onyx:0> false false or 1 sprint
false
onyx:0> true false or 1 sprint
true
onyx:0> 5 3 or 1 sprint
7
onyx:0>
array origin false:
array origin string line true:
Input(s):
array:
Output(s):
string:
A string (typically a filename) that tells what the origin of array was.
line:
An integer that represents the line within string that array started at.
false/true:
If false, no origin is recorded for array. If true, the origin is recorded for array, and string and line are also returned.
Error(s):
stackunderflow.
typecheck.
Description:
If the origin of array is recorded, return the string and line that represent the origin.
Example(s):
onyx:0> {} origin {exch 1 sprint 1 sprint} if
`*stdin*'
1
onyx:0> [] origin {exch 1 sprint 1 sprint} if
onyx:0>
- ostack stack:
Input(s):
None.
Output(s):
stack:
A current snapshot (copy) of ostack.
Error(s):
None.
Description:
Get a current snapshot of ostack.
Example(s):
onyx:0> 1 2 3 ostack pstack
(1 2 3)
3
2
1
onyx:4>
obj depth output -:
Input(s):
obj:
An object to print syntactically.
depth:
Maximum recursion depth.
Output(s):
None.
Error(s):
ioerror.
stackunderflow.
typecheck.
Description:
Syntactically print obj. See Section 2.11.7 for format specifier details.
Example(s):
onyx:0> [1 [2 3] 4] <$w 20 $p `_' $j $c $r 1> output `\n' print flush
___[1 -array- 4]____
onyx:0> [1 [2 3] 4] <$w 20 $p `_' $j $c $r 2> output `\n' print flush
____[1 [2 3] 4]_____
onyx:0> 4242 <$s $+> output `\n' print flush
+4242
onyx:0> `0x' print 4242 <$b 16> output `\n' print flush
0x1092
onyx:0> `0x' 4242 <$b 16> outputs cat <$w 10 $p `.'>
onyx:2>  output `\n' print flush
....0x1092
onyx:0> `0x' print 4242 <$w 8 $p `0' $b 16> output `\n' print flush
0x00001092
onyx:0>
obj flags outputs string:
Input(s):
obj:
An object to print syntactically.
depth:
Formatting flags. See Section 2.11.7 for details on the supported flags.
Output(s):
string:
A formatted string representation of obj. See Section 2.11.7 for format specifier details.
Error(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of obj.
Example(s):
onyx:0> [1 [2 3] 4] <$w 20 $p `_' $j $c $r 1> outputs print `\n' print flush
___[1 -array- 4]____
onyx:0> [1 [2 3] 4] <$w 20 $p `_' $j $c $r 2> outputs print `\n' print flush
____[1 [2 3] 4]_____
onyx:0> 4242 <$s $+> outputs print `\n' print flush
+4242
onyx:0> `0x' print 4242 <$b 16> outputs print `\n' print flush
0x1092
onyx:0> `0x' 4242 <$b 16> outputs cat <$w 10 $p `.'> outputs
onyx:1> print `\n' print flush
....0x1092
onyx:0> `0x' print 4242 <$w 8 $p `0' $b 16> outputs print `\n' print flush
0x00001092
onyx:0>
- outputsdict dict:
Input(s):
None.
Output(s):
dict:
A dictionary.
Error(s):
None.
Description:
Get outputsdict. See Section 2.11.7 for details on outputsdict.
Example(s):
onyx:0> outputsdict 0 sprint
-dict-
onyx:0>
a b over a b a:
Input(s):
a:
An object.
b:
An object.
Output(s):
a:
An object.
b:
An object.
Error(s):
stackunderflow.
Description:
Create a duplicate of the second object on ostack and push it onto ostack.
Example(s):
onyx:0> 0 1 2 over pstack
1
2
1
0
onyx:4>
prog path path/null:
Input(s):
prog:
A string that specifies a program to search for in the PATH environment variable.
Output(s):
path:
A string that specifies the path to prog.
null:
prog was not found.
Error(s):
stackunderflow.
typecheck.
Description:
Search for prog in the PATH, and return a string that is suitable for subsequent calls to operators such as exec , forkexec , and system .
Example(s):
onyx:0> `cat' path 1 sprint
`/bin/cat'
onyx:0>
sock peername dict:
Input(s):
sock:
A socket.
Output(s):
dict:
A dictionary of information about the peer end of sock. Depending on the socket family, the following entries may exist:
family:
Socket family.
address:
IPv4 address.
port:
IPv4 port.
path:
Unix-domain socket path.
Error(s):
argcheck.
ioerror.
neterror.
stackunderflow.
typecheck.
unregistered.
Description:
Get information about the peer end of sock.
Example(s):
onyx:0> $AF_INET $SOCK_STREAM socket
onyx:1> dup `localhost' 7777 bindsocket
onyx:1> dup listen
onyx:1> dup accept
onyx:2> dup peername 1 sprint
<$family $AF_INET $address 2130706433 $port 33746>
onyx:2>
- pid pid:
Input(s):
None.
Output(s):
pid:
Process identifier.
Error(s):
None.
Description:
Get the process ID of the running process.
Example(s):
onyx:0> pid 1 sprint
80624
onyx:0>
- pipe rfile wfile:
Input(s):
None.
Output(s):
rfile:
A readable file object. Data read from rfile were previously written to wfile.
wfile:
A writeable file object. Data written to wfile can subsequently be read from rfile.
Error(s):
ioerror.
unregistered.
Description:
Create a pipe.
Example(s):
onyx:0> pipe
onyx:2> $wfile exch def
onyx:1> $rfile exch def
onyx:0> wfile `foo\n' write
onyx:0> wfile flushfile
onyx:0> rfile readline pop 1 sprint
`foo'
onyx:0>
<file flags ...> timeout poll [file ...]:
Input(s):
<...>:
A dictionary of file/flags key/value pairs.
file:
A file object.
flags:
A dictionary that contains keys corresponding to file status attributes to poll. The following keys are heeded:
$POLLIN:
Normal or priority data are available for reading.
$POLLRDNORM:
Normal data are available for reading.
$POLLRDBAND:
Priority data are available for reading.
$POLLPRI:
High-priority data are available for reading.
$POLLOUT:
Normal data can be written.
$POLLWRNORM:
Normal data can be written.
$POLLWRBAND:
Priority data can be written.
The values associated with the keys are disregarded, but are set appropriately before poll returns (true/false).
timeout:
Timeout, in milliseconds (maximum $2^{31} - 1$). -1 is treated specially to mean infinite timeout.
Output(s):
[...]:
An array containing a reference to each file in <...> for which a non-zero number of status attributes is set to true. A zero-length array indicates that the poll timed out.
file:
A reference to a file object passed in that has one or more attributes set to true.
Although <...> is not returned, its contents are modified.
flags:
The dictionary passed in. For recognized key that is defined, the associated value is set to true or false, depending on the status of file. In addition, the following keys may defined (if not already defined) with a value of true in the case of errors:
$POLLERR:
An error has occurred.
$POLLHUP:
Hangup has occurred.
$POLLNVAL:
file is not an open file.
Error(s):
stackunderflow.
rangecheck.
typecheck.
Description:
Wait for any of the flags associated with a file in <...> to be true.
Example(s):
onyx:0> <stdout <$POLLOUT null> stderr <$POLLWRNORM null>> dup 0 poll
onyx:2> 2 sprint 2 sprint
[-file- -file-]
<-file- <$POLLWRNORM true> -file- <$POLLOUT true>>
onyx:0>
obj pop -:
Input(s):
obj:
An object.
Output(s):
None.
Error(s):
stackunderflow.
Description:
Remove the top object from ostack and discard it.
Example(s):
onyx:0> 1 2
onyx:2> pstack
2
1
onyx:2> pop
onyx:1> pstack
1
onyx:1>
a b pow r:
Input(s):
a:
An integer or real.
b:
An integer or real.
Output(s):
r:
a to the b power.
Error(s):
stackunderflow.
typecheck.
Description:
Return a to the b power. If a negative exponent is specified, the result will always be a real, even if both arguments are integers.
Example(s):
onyx:0> 5 0 pow 1 sprint
1
onyx:0> 5 1 pow 1 sprint
5
onyx:0> 5 2 pow 1 sprint
25
onyx:0> -5 3 pow 1 sprint
-125
onyx:0> 5 -3 pow 1 sprint
8.000000e-03
onyx:0> 2.1 3.5 pow 1 sprint
1.342046e+01
onyx:0> 100 .01 pow 1 sprint
1.000000e+02
onyx:0>
- ppid pid:
Input(s):
None.
Output(s):
pid:
Process identifier.
Error(s):
None.
Description:
Get the process ID of the running process's parent.
Example(s):
onyx:0> ppid 1 sprint
352
onyx:0>
string print -:
Input(s):
string:
A string object.
Output(s):
None.
Error(s):
ioerror.
stackunderflow.
typecheck.
Description:
Print string to stdout.
Example(s):
onyx:0> `Hi\n' print flush
Hi
onyx:0>
- product string:
Input(s):
None.
Output(s):
string:
A string that contains the product name, normally `Canonware Onyx'.
Error(s):
None.
Description:
Get the product string. The string returned is a reference to the original product string.
Example(s):
onyx:0> product pstack
`Canonware Onyx'
onyx:1>
- pstack -:
Input(s):
None.
Output(s):
None.
Error(s):
ioerror.
Description:
Syntactically print the elements of ostack, one per line.
Example(s):
onyx:0> `a' 1 mark $foo [1 2 3] (4 5 6)
onyx:6> pstack
(4 5 6)
[1 2 3]
$foo
-mark-
1
`a'
onyx:6>
array index obj put -:
dict key value put -:
string index integer put -:
Input(s):
array:
An array object.
dict:
A dict object.
string:
A string object.
index:
Offset in array or string to put obj or integer, respectively.
key:
An object to use as a key in dict.
obj:
An object to insert into array at offset index.
value:
An object to associate with key in dict.
integer:
The ascii value of a character to insert into string at offset index.
Output(s):
None.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Insert into array, dict, or string.
Example(s):
onyx:0> 3 array dup 1 `a' put 1 sprint
[null `a' null]
onyx:0> dict dup $foo `foo' put 1 sprint
<$foo `foo'>
onyx:0> 3 string dup 1 97 put 1 sprint
`\x00a\x00'
onyx:0>
array index subarray putinterval -:
string index substring putinterval -:
Input(s):
array:
An array object.
string:
A string object.
index:
Offset into array or string to put subarray or substring, respectively.
subarray:
An array object to put into array at offset index. When inserted subarray must not extend past the end of array.
substring:
A string object to put into string at offset index. When inserted substring must not extend past the end of string.
Output(s):
None.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Replace a portion of array or string.
Example(s):
onyx:0> 4 array dup 1 [`a' `b'] putinterval 1 sprint
[null `a' `b' null]
onyx:0> 4 string dup 1 `ab' putinterval 1 sprint
`\x00ab\x00'
onyx:0>
- pwd path:
Input(s):
None.
Output(s):
path:
A string that represents the present working directory.
Error(s):
invalidaccess.
Description:
Push a string onto ostack that represents the present working directory.
Example(s):
onyx:0> pwd
onyx:1> pstack
`/usr/local/bin'
onyx:1>
- quit -:
Input(s):
None.
Output(s):
None.
Error(s):
None.
Description:
Unwind the execution stack to the innermost start context. Under normal circumstances, there is always at least one such context.
Example(s):
onyx:0> stdin cvx start
onyx:0> estack 1 sprint
(--start-- -file- --start-- -file- --estack--)
onyx:0> quit
onyx:0> estack 1 sprint
(--start-- -file- --estack--)
onyx:0>
- rand integer:
Input(s):
None.
Output(s):
integer:
A pseudo-random non-negative integer, with 63 bits of psuedo-randomness.
Error(s):
None.
Description:
Return a pseudo-random integer.
Example(s):
onyx:0> 0 srand
onyx:0> rand 1 sprint
9018578418316157091
onyx:0> rand 1 sprint
8979240987855095636
onyx:0>
file read integer boolean:
file string read substring boolean:
Input(s):
file:
A file object.
string:
A string object.
Output(s):
integer:
An integer that represents the ascii value of a character that was read from file.
substring:
A substring of string that contains data read from file.
boolean:
If true, end of file reached during read.
Error(s):
ioerror.
stackunderflow.
typecheck.
Description:
Read from file.
Example(s):
onyx:0> `/tmp/foo' `w+' open
onyx:1> dup `Hello\n' write
onyx:1> dup flushfile
onyx:1> dup 0 seek
onyx:1> dup 10 string read
onyx:3> pop 1 sprint
`Hello\n'
file readline string boolean:
Input(s):
file:
A file object.
Output(s):
string:
A string that contains a line of text from file.
boolean:
If true, end of file reached during read.
Error(s):
ioerror.
stackunderflow.
typecheck.
Description:
Read a line of text from file. Lines are separated by ``\n'' or ``\r\n'', which is removed. The last line in a file may not have a newline at the end.
Example(s):
onyx:0> `/tmp/foo' `w+' open
onyx:1> dup `Hello\n' write
onyx:1> dup `Goodbye\n' write
onyx:1> dup 0 seek
onyx:1> dup readline 1 sprint 1 sprint
false
`Hello'
onyx:1> dup readline 1 sprint 1 sprint
false
`Goodbye'
onyx:1> dup readline 1 sprint 1 sprint
true
`'
onyx:1>
linkname readlink string:
Input(s):
linkname:
A string that represents the path of a symbolic link.
Output(s):
string:
A string that represents the link data associated with linkname.
Error(s):
invalidaccess.
invalidfileaccess.
ioerror.
stackunderflow.
typecheck.
undefinedfilename.
unregistered.
Description:
Get the data for the symbolic link at linkname.
Example(s):
onyx:0> `bar' `foo' symlink
onyx:0> `foo' readlink 1 sprint
`bar'
onyx:0>
- realtime nsecs:
Input(s):
None.
Output(s):
nsecs:
Number of nanoseconds since the epoch (midnight on 1 January 1970).
Error(s):
None.
Description:
Get the number of nanoseconds since the epoch.
Example(s):
onyx:0> realtime 1 sprint
993539837806479000
onyx:0>
sock string flags recv substring:
sock string recv substring:
Input(s):
sock:
A socket.
string:
A string to use as a buffer for the message being received.
flags:
An array of flag names. The following flags are supported:
$MSG_OOB
$MSG_PEEK
$MSG_WAITALL
Output(s):
substring:
A substring of string that contains message data.
Error(s):
argcheck.
neterror.
stackunderflow.
typecheck.
unregistered.
Description:
Example(s):
onyx:0> $AF_INET $SOCK_DGRAM socket
onyx:1> dup `localhost' 7777 bindsocket
onyx:1> dup true setnonblocking
onyx:1> dup 10 string recv
onyx:2> 1 sprint
`hello'
onyx:1>
string flags regex regex:
string regex regex:
Input(s):
string:
A string that specifies a regular expression. See Section 2.9 for syntax.
flags:
A dictionary of optional flags:
$c:
Continue where previous match ended. Don't update the offset to start the next match from unless this match is successful. Defaults to false.
$g:
Continue where previous match ended. If the match is unsuccessful, update the offset to start the next match from to the beginning of input. Defaults to false.
$i:
Case insensitive. Defaults to false.
$m:
Treat input as a multi-line string. Defaults to false.
$s:
Treat input as a single line, so that the dot metacharacter matches any character, including a newline. Defaults to false.
Output(s):
regex:
A regex object.
Error(s):
regexerror.
stackunderflow.
typecheck.
Description:
Create a regex object, according to string and flags.
Example(s):
onyx:0> `pattern' regex 1 sprint
-regex-
onyx:0> `pattern' <$g true> regex 1 sprint
-regex-
onyx:0>
pattern template flags regsub regsub:
pattern template regsub regsub:
Input(s):
pattern:
A string that specifies a regular expression. See Section 2.9 for syntax.
template:
A string that specifies a substitution template. See Section 2.9 for syntax.
flags:
A dictionary of optional flags:
$g:
Substitute all matches, if true, rather than just the first match. Defaults to false.
$i:
Case insensitive. Defaults to false.
$m:
Treat input as a multi-line string. Defaults to false.
$s:
Treat input as a single line, so that the dot metacharacter matches any character, including a newline. Defaults to false.
Output(s):
regsub:
A regsub object.
Error(s):
regexerror.
stackunderflow.
typecheck.
Description:
Create a regsub object, according to pattern, template, and flags.
Example(s):
onyx:0> `([a-z]+)' `<\1>' <$g true> regsub
onyx:1> 1 sprint
-regsub-
onyx:0>
old new rename -:
Input(s):
old:
A string object that represents a file path.
new:
A string object that represents a file path.
Output(s):
None.
Error(s):
invalidfileaccess.
ioerror.
limitcheck.
stackunderflow.
typecheck.
undefinedfilename.
Description:
Rename a file or directory from old to new.
Example(s):
onyx:0> `/tmp/tdir' 8@755 mkdir
onyx:0> `/tmp/tdir' `/tmp/ndir' rename
onyx:0> `/tmp/ndir' {1 sprint} dirforeach
`.'
`..'
onyx:0>
count proc repeat -:
Input(s):
count:
Number of times to evaluate proc (non-negative).
proc:
An object to evaluate.
Output(s):
None.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Evaluate proc count times. This operator supports the continue and exit operators.
Example(s):
onyx:0> 3 {`hi' 1 sprint} repeat
`hi'
`hi'
`hi'
onyx:0>
file require -:
Input(s):
file:
A string that represents a module filename.
Output(s):
None.
Error(s):
invalidfileaccess.
stackunderflow.
typecheck.
undefined.
undefinedfilename.
Description:
Search for and evaluate an Onyx source file. The file is searched for by catenating a prefix, a ``/'', and file to form a file path. Prefixes are tried in the following order:
  1. The ordered elements of the rpath_pre array, which is defined in onyxdict.
  2. If defined, the ordered elements of the ONYX_RPATH environment variable, which is a colon-separated list.
  3. The ordered elements of the rpath_post array, which is defined in onyxdict.
Example(s):
onyx:0> `modgtk/modgtk_defs.nx' require
onyx:0>
path rmdir -:
Input(s):
path:
A string object that represents a directory path.
Output(s):
None.
Error(s):
invalidfileaccess.
ioerror.
stackunderflow.
typecheck.
unregistered.
Description:
Remove an empty directory.
Example(s):
onyx:0> `/tmp/tdir' 8@755 mkdir
onyx:0> `/tmp/tdir' rmdir
onyx:0>
region count amount roll rolled:
Input(s):
region:
0 or more objects to be rolled.
count:
Number of objects in region.
amount:
Amount by which to roll. If positive, roll upward. If negative, roll downward.
Output(s):
rolled:
Rolled version of region.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Roll the top count objects on ostack (not counting count and amount) by amount positions. A positive amount indicates an upward roll, whereas a negative amount indicates a downward roll.
Example(s):
onyx:0> 3 2 1 0
onyx:4> pstack
0
1
2
3
onyx:4> 3 1 roll
onyx:4> pstack
1
2
0
3
onyx:4> 3 -2 roll
onyx:4> pstack
2
0
1
3
onyx:4> 4 0 roll
onyx:4> pstack
2
0
1
3
onyx:4>
a round r:
Input(s):
a:
An integer or real.
Output(s):
r:
Integer round of a.
Error(s):
stackunderflow.
typecheck.
Description:
Round a to the nearest integer and return the result.
Example(s):
onyx:0> -1.51 round 1 sprint
-2
onyx:0> -1.49 round 1 sprint
-1
onyx:0> 0 round 1 sprint
0
onyx:0> 1.49 round 1 sprint
1
onyx:0> 1.51 round 1 sprint
2
onyx:0>
...amount rot ...:
Input(s):
...:
One or more objects.
amount:
Number of positions to rotate the stack upward. A negative value causes downward rotation.
Output(s):
...:
One or more objects.
Error(s):
stackunderflow.
typecheck.
Description:
Rotate the stack contents up amount positions.
Example(s):
onyx:0> 1 2 3 4 5 2 rot pstack clear
3
2
1
5
4
onyx:0> 1 2 3 4 5 -2 rot pstack clear
2
1
5
4
3
onyx:0>
stack sadn -:
Input(s):
stack:
A stack object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Rotate the contents of stack down one position.
Example(s):
onyx:0> (1 2 3 4) dup sadn 1 sprint
(2 3 4 1)
onyx:0>
stack saup -:
Input(s):
stack:
A stack object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Rotate the contents of stack up one position.
Example(s):
onyx:0> (1 2 3 4) dup saup 1 sprint
(4 1 2 3)
onyx:0>
stack sbdup -:
Input(s):
stack:
A stack object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Duplicate the bottom object on stack and push it onto stack.
Example(s):
onyx:0> (2 1 0) dup sbdup pstack
(2 1 0 2)
onyx:1>
stack sbpop obj:
Input(s):
stack:
A stack object.
Output(s):
obj:
An object.
Error(s):
stackunderflow.
typecheck.
Description:
Pop obj off the bottom of stack.
Example(s):
onyx:0> (1 2 3) dup sbpop pstack
1
(2 3)
onyx:2>
stack obj sbpush -:
Input(s):
stack:
A stack object.
obj:
An object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Push obj onto the bottom of stack.
Example(s):
onyx:0> (0) dup 1 sbpush
onyx:1> pstack
(1 0)
onyx:1>
stack sclear -:
Input(s):
stack:
A stack object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Remove all objects on stack.
Example(s):
onyx:0> (1 2 3 4) dup sclear pstack
()
onyx:1>
stack scleartomark -:
Input(s):
stack:
A stack object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
unmatchedmark.
Description:
Remove objects from stack down to and including the topmost mark.
Example(s):
onyx:0> (3 mark 1 0) dup scleartomark pstack
(3)
onyx:1>
stack scount count:
Input(s):
stack:
A stack object.
Output(s):
count:
The number of objects on stack.
Error(s):
stackunderflow.
typecheck.
Description:
Get the number of objects on stack.
Example(s):
onyx:0> (1 2) scount 1 sprint
2
onyx:0>
stack scounttomark count:
Input(s):
stack:
A stack object.
Output(s):
count:
The depth of the topmost mark on stack.
Error(s):
stackunderflow.
typecheck.
unmatchedmark.
Description:
Get the depth of the topmost mark on stack.
Example(s):
onyx:0> (3 mark 1 0) scounttomark 1 sprint
2
onyx:0>
stack sdn -:
Input(s):
stack:
A stack object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Rotate the top three objects on stack down one position.
Example(s):
onyx:0> (3 2 1 0) dup sdn pstack
(3 1 0 2)
onyx:1>
stack sdup -:
Input(s):
stack:
A stack object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Duplicate the top object on stack and push it onto stack.
Example(s):
onyx:0> (1) dup sdup 1 sprint
(1 1)
onyx:0>
file offset seek -:
Input(s):
file:
A file object.
offset:
Offset in bytes from the beginning of file to move the file position pointer to.
Output(s):
None.
Error(s):
ioerror.
stackunderflow.
typecheck.
Description:
Move the file position pointer for file to offset.
Example(s):
onyx:0> `/tmp/foo' `w+' open
onyx:1> dup `Hello\n' write
onyx:1> dup 0 seek
onyx:1> readline pstack
false
`Hello'
onyx:2>
- self thread:
Input(s):
None.
Output(s):
thread:
A thread object that corresponds to the running thread.
Error(s):
None.
Description:
Get a thread object for the running thread.
Example(s):
onyx:0> self 1 sprint
-thread-
onyx:0>
sock mesg flags send nsend:
sock mesg send nsend:
Input(s):
sock:
A socket.
mesg:
A message string.
flags:
An array of flag names. The following flags are supported:
$MSG_OOB
$MSG_PEEK
$MSG_WAITALL
Output(s):
nsend:
Number of bytes of mesg actually sent.
Error(s):
argcheck.
neterror.
stackunderflow.
typecheck.
unregistered.
Description:
Send a message.
Example(s):
onyx:0> $AF_INET $SOCK_DGRAM socket
onyx:1> dup `localhost' 7777 connect
onyx:1> dup `hello' send
onyx:2> 1 sprint
5
onyx:1>
service serviceport port:
Input(s):
service:
A string that represents a network service name.
Output(s):
port:
The port number corresponding to service, or 0 if the service is unknown.
Error(s):
stackunderflow.
typecheck.
Description:
Example(s):
onyx:0> `ftp' serviceport 1 sprint
21
onyx:0>
class name/null setclassname -:
Input(s):
class:
A class object.
name/null:
A name or null object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Set class's name.
Example(s):
onyx:0> class dup $foo setclassname
onyx:1> classname 1 sprint
$foo
onyx:0>
class/instance dict/null setdata -:
Input(s):
class/instance:
A class or instance object.
dict/null:
A dict or null object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Set the data associated with class or instance.
Example(s):
onyx:0> class dup <$foo `foo'> setdata
onyx:1> data 1 sprint
<$foo `foo'>
onyx:0>
gid setegid boolean:
Input(s):
gid:
A group ID.
Output(s):
boolean:
If false, success, otherwise failure.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Set the process's effective group ID to gid.
Example(s):
onyx:0> 1001 setegid 1 sprint
false
onyx:0> 0 setegid 1 sprint
true
onyx:0>
key val setenv -:
Input(s):
key:
A name object.
val:
A value to associate with key.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Set an environment variable named key and associate val with it. If val is not a string, it is converted to a string using the cvs operator before the environment variable is set. A corresponding entry is also created in the envdict dictionary.
Example(s):
onyx:0> $foo `foo' setenv
onyx:0> envdict $foo known 1 sprint
true
onyx:0> envdict $foo get 1 sprint
`foo'
onyx:0> $foo unsetenv
onyx:0> envdict $foo known 1 sprint
false
onyx:0>
uid seteuid boolean:
Input(s):
uid:
A user ID.
Output(s):
boolean:
If false, success, otherwise failure.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Set the process's effective user ID to uid.
Example(s):
onyx:0> 1001 seteuid 1 sprint
false
onyx:0> 0 seteuid 1 sprint
true
onyx:0>
gid setgid boolean:
Input(s):
gid:
A group ID.
Output(s):
boolean:
If false, success, otherwise failure.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Set the process's group ID to gid.
Example(s):
onyx:0> 1001 setgid 1 sprint
false
onyx:0> 0 setgid 1 sprint
true
onyx:0>
count setgmaxestack -:
Input(s):
count:
Default maximum allowable estack depth.
Output(s):
None.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Set the default maximum allowable estack depth to count. This value is used when creating new threads.
Example(s):
onyx:0> 128 setgmaxestack
onyx:0>
file setgstderr -:
Input(s):
file:
A file to set the global stderr to.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Set the global stderr to file. See Section 2.4 for standard I/O details.
Example(s):
onyx:0> `/tmp/stderr' `w' open dup 0 setiobuf setgstderr
onyx:0> () {stderr `Some text\n' write} thread join
onyx:0> `/tmp/stderr' `r' open readline pop 1 sprint
`Some text'
onyx:0>
file setgstdin -:
Input(s):
file:
A file to set the global stdin to.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Set the global stdin to file. See Section 2.4 for standard I/O details.
Example(s):
Under normal interactive operation, stdin is pushed onto estack during interpreter initialization and evaluated until EOF is reached. Therefore, changing stdin has no effect on the file descriptor already on estack. The following example recursively evaluates stdin after redefining it.
lawine:~> cat /tmp/stdin
1 2 3 pstack
lawine:~> onyx
onyx:0> `/tmp/stdin' `r' open cvx setgstdin
onyx:0> () {stdin eval} thread join
3
2
1
onyx:0>
file setgstdout -:
Input(s):
file:
A file to set the global stdout to.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Set the global stdout to file. See Section 2.4 for standard I/O details.
Example(s):
In the following example, the prompt continues to be printed, even though stdout has been redefined, because the prompt module was initialized to print to file descriptor 1. This demonstrates the only known exception in the stock Onyx interpreter where redefining stdout will not redirect output.
onyx:0> `/tmp/stdout' `w' open dup 0 setiobuf setgstdout
onyx:0> () {`Some text\n' print} thread join
onyx:0> `/tmp/stdout' `r' open readline pop 1 sprint
`Some text'
onyx:0>
boolean setgtailopt -:
Input(s):
boolean:
If true, enable tail call optimization by default for new threads. Otherwise, do not enable tail call optimization by default for new threads.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Set whether to enable tail call optimization for new threads.
Example(s):
onyx:0> false setgtailopt
onyx:0>
file count setiobuf -:
Input(s):
file:
A file object.
count:
The size in bytes to set the I/O buffer associated with file to.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Set the size of the I/O buffer associated with file.
Example(s):
onyx:0> stdout iobuf 1 sprint
512
onyx:0> stdout 0 setiobuf
onyx:0> stdout iobuf 1 sprint
0
onyx:0>
instance class/null setisa -:
Input(s):
instance:
An instance object.
class/null:
A class or null object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Set the class associated with instance.
Example(s):
onyx:0> instance dup vclass setisa
onyx:1> isa classname 1 sprint
$vclass
onyx:0>
boolean setlocking -:
Input(s):
boolean:
A boolean to set the implicit locking mode to.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Set the current implicit locking mode. See Section 2.7.1 for implicit synchronization details.
Example(s):
onyx:0> currentlocking 1 sprint
false
onyx:0> true setlocking
onyx:0> currentlocking 1 sprint
true
onyx:0>
count setmaxestack -:
Input(s):
count:
Maximum allowable estack depth.
Output(s):
None.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Set the maximum allowable estack depth to count.
Example(s):
onyx:0> 128 setmaxestack
onyx:0>
class dict/null setmethods -:
Input(s):
class:
A class object.
dict/null:
A dict or null object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Set the methods associated with class.
Example(s):
onyx:0> class dup <$foo `foo'> setmethods
onyx:1> methods 1 sprint
<$foo `foo'>
onyx:0>
file boolean setnonblocking -:
Input(s):
file:
A file object.
boolean:
Non-blocking mode to set file to.
Output(s):
None.
Error(s):
ioerror.
stackunderflow.
typecheck.
Description:
Set non-blocking mode for file to boolean.
Example(s):
onyx:0> `/tmp/foo' `w' open
onyx:1> dup nonblocking 1 sprint
false
onyx:1> dup true setnonblocking
onyx:1> dup nonblocking 1 sprint
true
onyx:1>
pid pgid setpgid -:
Input(s):
pid:
Process ID, or 0 (same as specifying the calling process's ID).
pgid:
Process group ID.
Output(s):
None.
Error(s):
invalidaccess.
limitcheck.
rangecheck.
stackunderflow.
typecheck.
Description:
Example(s):
onyx:0> pid pid setpgid
onyx:0>
- setsid sid:
Input(s):
None.
Output(s):
sid:
Session ID.
Error(s):
invalidaccess.
stackunderflow.
typecheck.
Description:
Create a new session.
Example(s):
onyx:0> setsid
Error $invalidaccess
ostack: ()
dstack: (-dict- -dict- -dict- -dict-)
cstack: ()
estack/istack trace (0..2):
0:      --setsid--
1:      -file-
2:      --start--
onyx:1>
sock level optname optval setsockopt -:
sock optname optval setsockopt -:
Input(s):
sock:
A socket.
level:
Level at which to set the socket option. If not specified, $SOL_SOCKET is used.
optname:
Name of option to set the value of. The following option names are supported:
$SO_DEBUG
$SO_REUSEADDR
$SO_REUSEPORT
$SO_KEEPALIVE
$SO_DONTROUTE
$SO_BROADCAST
$SO_OOBINLINE
$SO_SNDBUF
$SO_RCVBUF
$SO_SNDLOWAT
$SO_RCVLOWAT
$SO_TYPE
$SO_ERROR:
optval is an integer.
$SO_LINGER:
optval is a dictionary, and the following entries are defined:
$on:
Boolean.
$time:
Linger time in seconds.
$SO_SNDTIMEO
$SO_RCVTIMEO:
optval is an integer, in nanoseconds.
optval:
Value to associate with optname.
Output(s):
None.
Error(s):
argcheck.
stackunderflow.
typecheck.
unregistered.
Description:
Set a socket option.
Example(s):
onyx:0> $AF_INET $SOCK_STREAM socket
onyx:1> dup $SO_OOBINLINE sockopt 1 sprint
0
onyx:1> dup $SO_OOBINLINE 1 setsockopt
onyx:1> dup $SO_OOBINLINE sockopt 1 sprint
1
onyx:1>
file setstderr -:
Input(s):
file:
A file to set the calling thread's stderr to.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Set the thread's stderr to file. See Section 2.4 for standard I/O details.
Example(s):
onyx:0> `/tmp/stderr' `w' open dup 0 setiobuf setstderr
onyx:0> stderr `Some text\n' write
onyx:0> `/tmp/stderr' `r' open readline pop 1 sprint
`Some text'
onyx:0>
file setstdin -:
Input(s):
file:
A file to set the calling thread's stdin to.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Set the thread's stdin to file. See Section 2.4 for standard I/O details.
Example(s):
Under normal interactive operation, stdin is pushed onto estack during interpreter initialization and evaluated until EOF is reached. Therefore, changing stdin has no effect on the file descriptor already on estack. The following example recursively evaluates stdin after redefining it.
lawine:~> cat /tmp/stdin
1 2 3 pstack
lawine:~> onyx
onyx:0> `/tmp/stdin' `r' open cvx setstdin
onyx:0> stdin eval
3
2
1
onyx:3>
file setstdout -:
Input(s):
file:
A file to set the calling thread's stdout to.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Set the thread's stdout to file. See Section 2.4 for standard I/O details.
Example(s):
In the following example, the prompt continues to be printed, even though stdout has been redefined, because the prompt module was initialized to print to file descriptor 1. This demonstrates the only known exception in the stock Onyx interpreter where redefining stdout will not redirect output.
onyx:0> `/tmp/stdout' `w' open dup 0 setiobuf setstdout
onyx:0> `Some text\n' print
onyx:0> gstdout setstdout
onyx:0> `/tmp/stdout' `r' open readline pop 1 sprint
`Some text'
onyx:0>
class super/null setsuper -:
Input(s):
class:
A class object.
super/null:
A class or null object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Set class's superclass.
Example(s):
onyx:0> class dup vclass setsuper
onyx:1> super classname 1 sprint
$vclass
onyx:0>
boolean settailopt -:
Input(s):
boolean:
If true, enable tail call optimization for this thread. Otherwise, disable tail call optimization for this thread.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Example(s):
onyx:0> $bar {estack 2 sprint} def
onyx:0> $foo {bar} def
onyx:0> foo
(--start-- -file- {estack 2 sprint} --estack--)
onyx:0> false settailopt
onyx:0> foo
(--start-- -file- {bar} {estack 2 sprint} --estack--)
onyx:0>
uid setuid boolean:
Input(s):
uid:
A user ID.
Output(s):
boolean:
If false, success, otherwise failure.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Set the process's user ID to uid.
Example(s):
onyx:0> 1001 setuid 1 sprint
false
onyx:0> 0 setuid 1 sprint
true
onyx:0>
stack sexch -:
Input(s):
stack:
A stack object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Exchange the top two objects on stack.
Example(s):
onyx:0> (1 2 3) dup sexch pstack
(1 3 2)
onyx:1>
- shift -:
Input(s):
a:
An integer.
shift:
An integer that represents a bitwise shift amount. Negative means right shift, and positive means left shift.
Output(s):
r:
a shifted by shift bits.
Error(s):
stackunderflow.
typecheck.
Description:
Shift an integer bitwise.
Example(s):
onyx:0> 4 1 shift 1 sprint
8
onyx:0> 4 -1 shift 1 sprint
2
onyx:0>
stack index sibdup -:
Input(s):
stack:
A stack object.
index:
Offset from bottom of stack, counting from 0, of the object to duplicate.
Output(s):
None.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Create a duplicate of the object on stack that is at offset index from the bottom of stack and push it onto stack.
Example(s):
onyx:0> (3 2 1 0) dup 2 sibdup pstack
(3 2 1 0 1)
onyx:1>
stack index sibpop obj:
Input(s):
stack:
A stack object.
index:
Offset from bottom of stack, counting from 0, of the object to remove from stack.
Output(s):
obj:
An object removed from stack.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Remove the obj from stack that is at offset index from the bottom of stack.
Example(s):
onyx:0> (0 1 2 3) dup 2 sibpop pstack
2
(0 1 3)
onyx:2>
stack index sidup -:
Input(s):
stack:
A stack object.
index:
Depth (count starts at 0) of the object to duplicate in stack.
Output(s):
None.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Create a duplicate of the object on stack at depth index and push it onto stack.
Example(s):
onyx:0> (3 2 1 0) dup 2 sidup
onyx:1> 1 sprint
(3 2 1 0 2)
onyx:0>
$SIG_GETMASK oset sigmask oset:
how set sigmask -:
how set oset sigmask oset:
Input(s):
how:
A name object:
$SIG_BLOCK:
Mask the union of the old mask set and the signals in set whose values are set to true.
$SIG_UNBLOCK:
Unmask the signals in set whose values are set to true.
$SIG_GETMASK:
Get the current signal mask.
$SIG_SETMASK:
Set the signal mask to the signals in set whose values are set to true.
set:
A dictionary of signal name and/or integers keys, with associated true/false values. A value of true indicates set membership. The recognized names are:
  • $SIGABRT
  • $SIGALRM
  • $SIGBUS
  • $SIGCHLD
  • $SIGCONT
  • $SIGFPE
  • $SIGHUP
  • $SIGILL
  • $SIGINT
  • $SIGKILL
  • $SIGPIPE
  • $SIGQUIT
  • $SIGSEGV
  • $SIGSTOP
  • $SIGTERM
  • $SIGTSTP
  • $SIGTTIN
  • $SIGTTOU
  • $SIGUSR1
  • $SIGUSR2
  • $SIGPOLL (may not be present)
  • $SIGPROF
  • $SIGSYS
  • $SIGTRAP
  • $SIGURG
  • $SIGVTALRM (may not be present)
  • $SIGXCPU
  • $SIGXFSZ
oset:
A dictionary of signal name keys, with associated true/false values. This dictionary contains the signal mask as it was prior to execution of this operator.
Output(s):
oset:
The same dictionary as was passed in as oset.
Error(s):
argcheck.
stackunderflow.
typecheck.
Description:
Get or set the calling thread's current signal mask.
Example(s):
onyx:0> $SIG_GETMASK <> sigmask 1 sprint
<$SIGHUP true $SIGINT true $SIGQUIT true $SIGTERM true>
onyx:0> $SIG_BLOCK <$SIGPIPE true> <> sigmask 1 sprint
<$SIGHUP true $SIGINT true $SIGQUIT true $SIGTERM true>
onyx:0> $SIG_GETMASK <> sigmask 1 sprint
<$SIGHUP true $SIGINT true $SIGPIPE true $SIGQUIT true $SIGTERM true>
onyx:0> $SIG_UNBLOCK <$SIGPIPE true> <> sigmask 1 sprint
<$SIGHUP true $SIGINT true $SIGPIPE true $SIGQUIT true $SIGTERM true>
onyx:0> $SIG_GETMASK <> sigmask 1 sprint
<$SIGHUP true $SIGINT true $SIGQUIT true $SIGTERM true>
onyx:0>
condition signal -:
Input(s):
condition:
A condition object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Signal a thread that is waiting on condition. If there are no waiters, this operator has no effect.
Example(s):
onyx:0> condition mutex dup lock ostack
onyx:3> {dup lock exch signal unlock}
onyx:4> thread 3 1 roll
onyx:3> dup 3 1 roll
onyx:4> wait unlock join
onyx:0>
set sigpending set:
Input(s):
set:
A dictionary.
Output(s):
set:
The same dictionary as the input set. A dictionary of signal name keys, with associated true values. A value of true indicates set membership. The supported names are:
  • $SIGABRT
  • $SIGALRM
  • $SIGBUS
  • $SIGCHLD
  • $SIGCONT
  • $SIGFPE
  • $SIGHUP
  • $SIGILL
  • $SIGINT
  • $SIGKILL
  • $SIGPIPE
  • $SIGQUIT
  • $SIGSEGV
  • $SIGSTOP
  • $SIGTERM
  • $SIGTSTP
  • $SIGTTIN
  • $SIGTTOU
  • $SIGUSR1
  • $SIGUSR2
  • $SIGPOLL (may not be present)
  • $SIGPROF
  • $SIGSYS
  • $SIGTRAP
  • $SIGURG
  • $SIGVTALRM (may not be present)
  • $SIGXCPU
  • $SIGXFSZ
Error(s):
stackunderflow.
typecheck.
Description:
Get pending signals.
Example(s):
onyx:0> <> sigpending 1 sprint
<>
onyx:0>
set sigsuspend -:
Input(s):
set:
A dictionary of signal name and/or integers keys, with associated true/false values. A value of true indicates set membership. The recognized names are:
  • $SIGABRT
  • $SIGALRM
  • $SIGBUS
  • $SIGCHLD
  • $SIGCONT
  • $SIGFPE
  • $SIGHUP
  • $SIGILL
  • $SIGINT
  • $SIGKILL
  • $SIGPIPE
  • $SIGQUIT
  • $SIGSEGV
  • $SIGSTOP
  • $SIGTERM
  • $SIGTSTP
  • $SIGTTIN
  • $SIGTTOU
  • $SIGUSR1
  • $SIGUSR2
  • $SIGPOLL (may not be present)
  • $SIGPROF
  • $SIGSYS
  • $SIGTRAP
  • $SIGURG
  • $SIGVTALRM (may not be present)
  • $SIGXCPU
  • $SIGXFSZ
Output(s):
None.
Error(s):
argcheck.
stackunderflow.
typecheck.
Description:
Suspend the calling thread until one of the signals in set is caught.
Example(s):
onyx:0> <> sigsuspend
onyx:0>
set sigwait sig:
Input(s):
set:
A dictionary of signal name and/or integers keys, with associated true/false values. A value of true indicates set membership. The recognized names are:
  • $SIGABRT
  • $SIGALRM
  • $SIGBUS
  • $SIGCHLD
  • $SIGCONT
  • $SIGFPE
  • $SIGHUP
  • $SIGILL
  • $SIGINT
  • $SIGKILL
  • $SIGPIPE
  • $SIGQUIT
  • $SIGSEGV
  • $SIGSTOP
  • $SIGTERM
  • $SIGTSTP
  • $SIGTTIN
  • $SIGTTOU
  • $SIGUSR1
  • $SIGUSR2
  • $SIGPOLL (may not be present)
  • $SIGPROF
  • $SIGSYS
  • $SIGTRAP
  • $SIGURG
  • $SIGVTALRM (may not be present)
  • $SIGXCPU
  • $SIGXFSZ
Output(s):
sig:
One of the signal names that was specified in set.
Error(s):
argcheck.
stackunderflow.
typecheck.
Description:
Wait for one of the signals in set, and return the name of the signal that was caught.
Example(s):
onyx:0> $SIG_BLOCK <$SIGXCPU true> sigmask
onyx:0> <$SIGXCPU true> sigwait
onyx:1> 1 sprint
$SIGXCPU
onyx:0>
a sin r:
Input(s):
a:
An integer or real.
Output(s):
r:
Sine of a in radians.
Error(s):
stackunderflow.
typecheck.
Description:
Return the sine of a in radians.
Example(s):
onyx:0> 0 sin 1 sprint
0.000000e+00
onyx:0> 1.570796 sin 1 sprint
1.000000e+00
onyx:0> 0.7853982 sin 1 sprint
7.071068e-01
onyx:0>
a sinh r:
Input(s):
a:
An integer or real.
Output(s):
r:
Hyperbolic sine of a.
Error(s):
stackunderflow.
typecheck.
Description:
Return the hyperbolic sine of a.
Example(s):
onyx:0> 3 sinh 1 sprint
1.001787e+01
onyx:0>
stack index sipop obj:
Input(s):
stack:
A stack object.
index:
Offset from top of stack, counting from 0, of the object to remove from stack.
Output(s):
obj:
An object removed from stack.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Remove the obj at index from stack.
Example(s):
onyx:0> (3 2 1 0) dup 2 sipop pstack
2
(3 1 0)
onyx:2>
stack count snbpop array:
Input(s):
stack:
A stack object.
count:
Number of objects to pop off the bottom of stack.
Output(s):
array:
An array of objects popped off the bottom of stack, with the same object ordering as when on stack.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Pop count objects off the bottom of stack and put them into an array.
Example(s):
onyx:0> (1 2 3 4) dup 2 snbpop pstack
[1 2]
(3 4)
onyx:2>
stack count sndn -:
Input(s):
stack:
A stack object.
count:
Number of objects on stack to rotate down one position.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Rotate count objects on stack down one position.
Example(s):
onyx:0> (5 4 3 2 1 0) dup 4 sndn pstack
(5 4 2 1 0 3)
onyx:1>
stack count sndup -:
Input(s):
stack:
A stack object.
count:
Number of objects on stack to duplicate.
Output(s):
None.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Create duplicates of the top count objects on stack.
Example(s):
onyx:0> (3 2 1 0) dup 2 sndup pstack
(3 2 1 0 1 0)
onyx:1>
stack snip obj:
Input(s):
stack:
A stack object.
Output(s):
obj:
The object that was the second to top object on stack.
Error(s):
stackunderflow.
typecheck.
Description:
Remove the second to top object from stack.
Example(s):
onyx:0> (2 1 0) dup snip pstack
1
(2 0)
onyx:2>
stack count snpop array:
Input(s):
stack:
A stack object.
count:
Number of objects to pop off of stack.
Output(s):
array:
An array of objects popped off of stack, with the same object ordering as when on stack.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Pop count objects off of stack and put them into an array.
Example(s):
onyx:0> (1 2 3 4) dup 2 snpop pstack
[3 4]
(1 2)
onyx:2>
stack count snup -:
Input(s):
stack:
A stack object.
count:
Number of objects on stack to rotate up one position.
Output(s):
None.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Rotate count objects on stack up one position.
Example(s):
onyx:0> (5 4 3 2 1 0) dup 4 snup pstack
(5 4 0 3 2 1)
onyx:1>
family type proto socket sock:
family type socket sock:
Input(s):
family:
The name of a socket address family, either $AF_INET or $AF_LOCAL.
type:
The name of a socket type, either $SOCK_STREAM or $SOCK_DGRAM.
proto:
The name of a socket protocol. This argument is not useful, given the current limited choice of address families.
Output(s):
sock:
A socket.
Error(s):
argcheck.
invalidaccess.
stackunderflow.
typecheck.
unregistered.
Description:
Create a socket.
Example(s):
onyx:0> $AF_INET $SOCK_STREAM socket
onyx:1> $AF_LOCAL $SOCK_DGRAM socket
onyx:2>
family type proto socketpair sock sock:
family type socketpair sock sock:
Input(s):
family:
The name of a socket address family, either $AF_INET or $AF_LOCAL.
type:
The name of a socket type, either $SOCK_STREAM or $SOCK_DGRAM.
proto:
The name of a socket protocol. This argument is not useful, given the current limited choice of address families.
Output(s):
sock:
A connected socket. There are no functional differences between the two sockets that are returned.
Error(s):
argcheck.
invalidaccess.
stackunderflow.
typecheck.
unregistered.
Description:
Create a pair of sockets that are connected to each other.
Example(s):
onyx:0> $AF_LOCAL $SOCK_STREAM socketpair
onyx:2> pstack
-file-
-file-
onyx:2>
sock sockname dict:
Input(s):
sock:
A socket.
Output(s):
dict:
A dictionary of information about sock. Depending on the socket family, the following entries may exist:
family:
Socket family.
address:
IPv4 address.
port:
IPv4 port.
path:
Unix-domain socket path.
Error(s):
argcheck.
ioerror.
neterror.
stackunderflow.
typecheck.
unregistered.
Description:
Get information about sock.
Example(s):
onyx:0> $AF_INET $SOCK_STREAM socket
onyx:1> dup `localhost' bindsocket
onyx:1> dup sockname 1 sprint
<$family $AF_INET $address 2130706433 $port 33745>
onyx:1> close
onyx:0> $AF_LOCAL $SOCK_STREAM socket
onyx:1> dup `/tmp/socket' bindsocket
onyx:1> dup sockname 1 sprint
<$family $AF_LOCAL $path `/tmp/socket'>
onyx:1>
sock level optname sockopt optval:
sock optname sockopt optval:
Input(s):
sock:
A socket.
level:
Level at which to get the socket option. If not specified, $SOL_SOCKET is used.
optname:
Name of option to get the value of. The following option names are supported:
$SO_DEBUG
$SO_REUSEADDR
$SO_REUSEPORT
$SO_KEEPALIVE
$SO_DONTROUTE
$SO_BROADCAST
$SO_OOBINLINE
$SO_SNDBUF
$SO_RCVBUF
$SO_SNDLOWAT
$SO_RCVLOWAT
$SO_TYPE
$SO_ERROR:
optval is an integer.
$SO_LINGER:
optval is a dictionary, and the following entries are defined:
$on:
Boolean.
$time:
Linger time in seconds.
$SO_SNDTIMEO
$SO_RCVTIMEO:
optval is an integer, in nanoseconds.
Output(s):
optval:
Value associated with optname.
Error(s):
argcheck.
stackunderflow.
typecheck.
unregistered.
Description:
Get a socket option.
Example(s):
onyx:0> $AF_INET $SOCK_STREAM socket
onyx:1> dup $SO_SNDBUF sockopt 1 sprint
16384
onyx:1>
stack sover -:
Input(s):
stack:
A stack object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Create a duplicate of the second object on stack and push it onto stack.
Example(s):
onyx:0> (2 1 0) dup sover pstack
(2 1 0 1)
onyx:1>
input pattern flags limit split array:
input pattern flags split array:
input pattern limit split array:
input pattern split array:
input regex limit split array:
input regex split array:
Input(s):
input:
An input string to find matches in.
pattern:
A string that specifies a regular expression. See Section 2.9 for syntax.
flags:
A dictionary of optional flags:
$i:
Case insensitive. Defaults to false.
$m:
Treat input as a multi-line string. Defaults to false.
$s:
Treat input as a single line, so that the dot metacharacter matches any character, including a newline. Defaults to false.
regex:
A regex object.
limit:
Split input into no more than limit substrings. 0 is treated as infinity. Defaults to 0.
Output(s):
array:
An array of substrings containing the text between pattern matches.
Error(s):
rangecheck.
regexerror.
stackunderflow.
typecheck.
Description:
Create an array of substrings from input that are separated by portions of input that match a regular expression.

If there are capturing subpatterns in the regular expression, also create substrings for those capturing subpatterns and insert them into the substring array.

As a special case, if the regular expression matches the empty string, split a single character. This avoids an infinite loop.

Example(s):
onyx:0> `a:b:c' `:' split 1 sprint
[`a' `b' `c']
onyx:0> `a:b:c' `:' 2 split 1 sprint
[`a' `b:c']
onyx:0> `a:b:c' `(:)' split 1 sprint
[`a' `:' `b' `:' `c']
onyx:0> `a:b:c' `' split 1 sprint
[`a' `:' `b' `:' `c']
onyx:0>
stack spop obj:
Input(s):
stack:
A stack object.
Output(s):
obj:
The object that was popped off of stack.
Error(s):
stackunderflow.
typecheck.
Description:
Pop an object off of stack and push it onto ostack.
Example(s):
onyx:0> (1 2) dup spop
onyx:2> pstack
2
(1)
onyx:2>
obj depth sprint -:
Input(s):
obj:
An object to print syntactically.
depth:
Maximum recursion depth.
Output(s):
None.
Error(s):
ioerror.
stackunderflow.
typecheck.
Description:
Syntactically print obj. See Section 2.11.8 for printing details.
Example(s):
onyx:0> [1 [2 3] 4]
onyx:1> dup 0 sprint
-array-
onyx:1> dup 1 sprint
[1 -array- 4]
onyx:1> dup 2 sprint
[1 [2 3] 4]
onyx:1>
obj depth sprints string:
Input(s):
obj:
An object to print syntactically.
depth:
Maximum recursion depth.
Output(s):
string:
A syntactical string representation of obj. See Section 2.11.8 for printing details.
Error(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of obj.
Example(s):
onyx:0> [1 [2 3] 4]
onyx:1> dup 0 sprints print `\n' print flush
-array-
onyx:1> dup 1 sprints print `\n' print flush
[1 -array- 4]
onyx:1> dup 2 sprints print `\n' print flush
[1 [2 3] 4]
onyx:1>
- sprintsdict dict:
Input(s):
None.
Output(s):
dict:
A dictionary.
Error(s):
None.
Description:
Get sprintsdict. See Section 2.11.8 for details on sprintsdict.
Example(s):
onyx:0> sprintsdict 0 sprint
-dict-
onyx:0>
stack obj spush -:
Input(s):
stack:
A stack object.
obj:
An object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Push obj onto stack.
Example(s):
onyx:0> (0) dup 1 spush
onyx:1> pstack
(0 1)
onyx:1>
a sqrt r:
Input(s):
a:
A non-negative integer or real.
Output(s):
r:
Square root of a.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Return the square root of a.
Example(s):
onyx:0> 4 sqrt 1 sprint
2.000000e+00
onyx:0> 2.0 sqrt 1 sprint
1.414214e+00
onyx:0>
seed srand -:
Input(s):
seed:
A non-negative integer.
Output(s):
None.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Seed the pseudo-random number generator with seed.
Example(s):
onyx:0> 5 srand
onyx:0>
stack count amount sroll -:
Input(s):
stack:
A stack object.
count:
Number of objects to roll in stack.
amount:
Amount by which to roll. If positive, roll upward. If negative, roll downward.
Output(s):
None.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Roll the top count objects on stack by amount positions. A positive amount indicates an upward roll, whereas a negative amount indicates a downward roll.
Example(s):
onyx:0> (3 2 1 0)
onyx:1> dup 3 1 sroll pstack
(3 0 2 1)
onyx:1> dup 3 -2 sroll pstack
(3 1 0 2)
onyx:1> dup 4 0 sroll pstack
(3 1 0 2)
onyx:1>
stack amount srot -:
Input(s):
stack:
One or more objects.
amount:
Number of positions to rotate stack upward. A negative value causes downward rotation.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Rotate stack up count positions.
Example(s):
onyx:0> (1 2 3 4 5) dup 2 srot 1 sprint
(4 5 1 2 3)
onyx:0> (1 2 3 4 5) dup -2 srot 1 sprint
(3 4 5 1 2)
onyx:0>
- stack stack:
Input(s):
None.
Output(s):
stack:
An empty stack object.
Error(s):
None.
Description:
Create a new stack object and push it onto ostack.
Example(s):
onyx:0> stack
onyx:1> pstack
()
obj start -:
Input(s):
obj:
An object.
Output(s):
None.
Error(s):
stackunderflow.
Description:
Evaluate obj. This operator provides a context that silently terminates execution stack unwinding due to the exit , quit , and stop operators.
Example(s):
onyx:0> stdin cvx start
onyx:0> quit
onyx:0>
file/filename status dict:
Input(s):
file:
A file object.
filename:
A string that represents a filename.
Output(s):
dict:
A dictionary that contains the following entries:
dev:
Inode's device.
ino:
Inode's number.
mode:
Inode permissions.
nlink:
Number of hard links.
uid:
User ID of the file owner.
gid:
Group ID of the file owner.
rdev:
Device type.
size:
File size in bytes.
atime:
Time of last access, in nanoseconds since the epoch.
mtime:
Time of last modification, in nanoseconds since the epoch.
ctime:
Time of last file status change, in nanoseconds since the epoch.
blksize:
Optimal block size for I/O.
blocks:
Number of blocks allocated.
Error(s):
invalidfileaccess.
ioerror.
stackunderflow.
typecheck.
unregistered.
Description:
Get status information about a file.
Example(s):
onyx:0> `/tmp' status 1 sprint
<$dev 134405 $ino 2 $mode 17407 $nlink 5 $uid 0 $gid 0 $rdev 952 $size 3584
$atime 994883041000000000 $mtime 994883041000000000 $ctime 994883041000000000
$blksize 0 $blocks 8>
onyx:0>
- stderr file:
Input(s):
None.
Output(s):
file:
A file object corresponding to the calling thread's stderr.
Error(s):
None.
Description:
Get the thread's stderr. See Section 2.4 for standard I/O details.
Example(s):
onyx:0> stderr pstack
-file-
onyx:1>
- stdin file:
Input(s):
None.
Output(s):
file:
A file object corresponding to the calling thread's stdin.
Error(s):
None.
Description:
Get the thread's stdin. See Section 2.4 for standard I/O details.
Example(s):
onyx:0> stdin pstack
-file-
onyx:1>
- stdout file:
Input(s):
None.
Output(s):
file:
A file object corresponding to the calling thread's stdout.
Error(s):
None.
Description:
Get the thread's stdout. See Section 2.4 for standard I/O details.
Example(s):
onyx:0> stdout pstack
-file-
onyx:1>
- stop -:
Input(s):
None.
Output(s):
None.
Error(s):
None.
Description:
Unwind the execution stack to the innermost stopped or start context.
Example(s):
onyx:0> {stop} stopped 1 sprint
true
onyx:0>
obj stopped boolean:
Input(s):
obj:
An object to evaluate.
Output(s):
boolean:
True if stop operator was executed, false otherwise.
Error(s):
invalidcontinue.
invalidexit.
stackunderflow.
Description:
Evaluate obj. This operator provides a context that terminates execution stack unwinding due to the stop operator. It will also terminate execution stack unwinding due to the continue and exit operators, but will throw an invalidcontinue or invalidexit error, respectively, then do the equivalent of calling quit .
Example(s):
onyx:0> {stop} stopped 1 sprint
true
onyx:0> {} stopped 1 sprint
false
onyx:0>
length string string:
Input(s):
length:
Non-negative number of bytes.
Output(s):
string:
A string of length bytes.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Create a string of length bytes. The bytes are initialized to 0.
Example(s):
onyx:0> 3 string 1 sprint
`\x00\x00\x00'
onyx:0>
onyx:0> 0 string 1 sprint
`'
onyx:0>
stack stuck -:
Input(s):
stack:
A stack object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Tuck duplicate of top object on stack under second object on stack.
Example(s):
onyx:0> (2 1 0) dup stuck pstack
(2 0 1 0)
onyx:1>
a b sub r:
Input(s):
a:
An integer or real.
b:
An integer or real.
Output(s):
r:
The value of b subtracted from a.
Error(s):
stackunderflow.
typecheck.
Description:
Subtract b from a and return the result.
Example(s):
onyx:0> 5 3 sub 1 sprint
2
onyx:0> -3 4 sub 1 sprint
-7
onyx:0> 5.1 1.1 sub 1 sprint
4.000000e+00
onyx:0> 5 1.0 sub 1 sprint
4.000000e+00
onyx:0> -3.0 4.1 sub 1 sprint
-7.100000e+00
onyx:0>
integer submatch substring:
Input(s):
integer:
0:
Get substring of text that matched the regular expression.
>0:
Get substring of text that matched the specified capturing subpattern.
Output(s):
substring:
A substring of the string that was most recently matched by the match , split , or subst operators.
Error(s):
stackunderflow.
typecheck.
Description:
Get a substring of the input string that was most recently matched against.
Example(s):
onyx:0> `input' `n(p)u' match {0 submatch 1 sprint 1 submatch 1 sprint} if
`npu'
`p'
onyx:0>
input pattern template flags subst output count:
input pattern template subst output count:
input regsub subst output count:
Input(s):
input:
An input string.
pattern:
A string that specifies a regular expression. See Section 2.9 for syntax.
template:
A string that specifies a substitution template. See Section 2.9 for syntax.
flags:
A dictionary of optional flags:
$g:
Substitute all matches, if true, rather than just the first match. Defaults to false.
$i:
Case insensitive. Defaults to false.
$m:
Treat input as a multi-line string. Defaults to false.
$s:
Treat input as a single line, so that the dot metacharacter matches any character, including a newline. Defaults to false.
regsub:
A regsub object.
Output(s):
output:
A string that is created by substituting substrings within input that match a regular expression.
count:
Number of substitutions made. If 0 substitutions were made, then output is a duplicate of input, rather than a copy.
Error(s):
regexerror.
stackunderflow.
typecheck.
Description:
Create a string by substituting according to a template for each substring within input that matches a regular expression.
Example(s):
onyx:0> `Input String' `([a-r])' `[\1]' <$g true> subst pstack
6
`I[n][p]ut St[r][i][n][g]'
onyx:2>
stack sunder -:
Input(s):
stack:
A stack object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Create a duplicate of the second object on stack and put it under the top object on stack.
Example(s):
onyx:0> (2 1 0) dup sunder pstack
(2 1 1 0)
onyx:1>
stack sup -:
Input(s):
stack:
A stack object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Rotate the top three objects on stack up one position.
Example(s):
onyx:0> (3 2 1 0) dup sup pstack
(3 0 2 1)
onyx:1>
class super super/null:
Input(s):
class:
A class object.
Output(s):
super/null:
A class or null object.
Error(s):
stackunderflow.
typecheck.
Description:
Get the superclass of class.
Example(s):
onyx:0> class super 1 sprint
null
onyx:0> class dup vclass setsuper
onyx:1> super classname 1 sprint
$vclass
onyx:0>
filename linkname symlink -:
Input(s):
filename:
A string that represents a filename.
linkname:
A string that represents a filename.
Output(s):
None.
Error(s):
invalidfileaccess.
ioerror.
stackunderflow.
typecheck.
undefinedfilename.
unregistered.
Description:
Create a symbolic link from linkname to filename.
Example(s):
onyx:0> `/tmp/foo' `w' open
onyx:1> dup `Hello\n' write
onyx:1> dup flushfile
onyx:1> close
onyx:0> `/tmp/foo' `/tmp/bar' symlink
onyx:0> `/tmp/bar' `r' open
onyx:1> readline
onyx:2> pstack
false
`Hello'
onyx:2>
- tailopt boolean:
Input(s):
None.
Output(s):
boolean:
True if tail call optimization is enabled for this thread; false otherwise.
Error(s):
None.
Description:
Get whether tail call optimization is enabled for this thread.
Example(s):
onyx:0> tailopt 1 sprint
true
onyx:0>
args system status:
Input(s):
args:
An array of strings. The first string in args is the path of the program to invoke, and any additional array elements are passed as command line arguments to the invoked program.
Output(s):
status:
Exit code of terminated process. A negative value indicates that the process was terminated by a signal (use the neg operator to get the signal number), and a non-negative value is the exit code of a program that terminated normally.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Execute a program as a child process and wait for it to terminate.
Example(s):
onyx:0> [`/usr/bin/which' `onyx'] system
/usr/local/bin/onyx
onyx:1> 1 sprint
0
onyx:0>
- systemdict dict:
Input(s):
None.
Output(s):
dict:
A dictionary.
Error(s):
None.
Description:
Get systemdict. See Section 2.11.9 for details on systemdict.
Example(s):
onyx:0> systemdict 0 sprint
-dict-
onyx:0>
a sinh r:
Input(s):
a:
An integer or real.
Output(s):
r:
Tangent of a in radians.
Error(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Return the tangent of a in radians.
Example(s):
onyx:0> 0.785 tan 1 sprint
9.992040e-01
onyx:0>
a tanh r:
Input(s):
a:
An integer or real.
Output(s):
r:
Hyperbolic tangent of a.
Error(s):
stackunderflow.
typecheck.
Description:
Return the hyperbolic tangent of a.
Example(s):
onyx:0> 3 tanh 1 sprint
9.950548e-01
onyx:0>
file tell offset:
Input(s):
fil:
A file object.
Output(s):
offset:
Offset of the file position pointer for file.
Error(s):
ioerror.
stackunderflow.
typecheck.
Description:
Get the file position pointer offset for file.
Example(s):
onyx:0> `/tmp/foo' `w+' open
onyx:1> dup tell 1 sprint
0
onyx:1> dup `Hello\n' write
onyx:1> dup tell 1 sprint
6
onyx:1>
file/filename flag test boolean:
Input(s):
file:
A file object.
filename:
A string that represents a filename.
flag:
A single-character string that represents the test to do on file or filename:
`b':
Block special device?
`c':
Character special device?
`d':
Directory?
`e':
Exists?
`f':
Regular file?
`g':
Setgid?
`k':
Sticky?
`p':
Named pipe?
`r':
Readable?
`s':
Size greater than 0?
`t':
tty?
`u':
Setuid?
`w':
Write bit set?
`x':
Executable bit set?
`L':
Symbolic link?
`O':
Owner matches effective uid?
`G':
Group matches effective gid?
`S':
Socket?
Output(s):
boolean:
If true, the test evaluated to true; false otherwise.
Error(s):
invalidfileaccess.
ioerror.
rangecheck.
stackunderflow.
typecheck.
unregistered.
Description:
Test a file for an attribute.
Example(s):
onyx:0> `/blah' `e' test 1 sprint
false
onyx:0> `/tmp' `e' test 1 sprint
true
onyx:0>
- this class/instance:
Input(s):
None.
Output(s):
class:
A class object.
instance:
An instance object.
Error(s):
stackunderflow.
Description:
Get the topmost object on cstack, which provides the context for execution of invokable and fetchable objects.
Example(s):
onyx:0> $fooclass vclass <> <$foomethod {this:classname 1 sprint}> cdef
onyx:0> fooclass:foomethod
$fooclass
onyx:0>
stack entry thread thread:
Input(s):
stack:
A stack that contains the contents for the new thread's ostack.
entry:
An initial object to execute in the new thread.
Output(s):
thread:
A thread object that corresponds to the new thread.
Error(s):
stackunderflow.
typecheck.
Description:
Create and run a new thread.
Example(s):
onyx:0> (1 2) {add 1 sprint} thread join `Done\n' print flush
3
Done
onyx:0>
thread threadcstack stack:
Input(s):
thread:
A thread object.
Output(s):
stack:
The context stack belonging to thread.
Error(s):
stackunderflow.
typecheck.
Description:
Get a reference to the context stack belonging to thread.
Example(s):
onyx:0> self threacdstack 1 sprint
()
onyx:0>
thread threaddstack stack:
Input(s):
thread:
A thread object.
Output(s):
stack:
The dictionary stack belonging to thread.
Error(s):
stackunderflow.
typecheck.
Description:
Get a reference to the dictionary stack belonging to thread.
Example(s):
onyx:0> self threaddstack 1 sprint
(-dict- -dict- -dict- -dict-)
onyx:0>
thread threadestack stack:
Input(s):
thread:
A thread object.
Output(s):
stack:
The execution stack belonging to thread.
Error(s):
stackunderflow.
typecheck.
Description:
Get a reference to the execution stack belonging to thread.
Example(s):
onyx:0> self threadestack 1 sprint
(-file- -array- --eval-- --ifelse-- -array- --for-- -array-)
onyx:0>
thread threadistack stack:
Input(s):
thread:
A thread object.
Output(s):
stack:
The index stack belonging to thread.
Error(s):
stackunderflow.
typecheck.
Description:
Get a reference to the index stack belonging to thread.
Example(s):
onyx:0> self threadistack 1 sprint
(0 0 0 0 7 0 3)
onyx:0>
thread threadostack stack:
Input(s):
thread:
A thread object.
Output(s):
stack:
The operand stack belonging to thread.
Error(s):
stackunderflow.
typecheck.
Description:
Get a reference to the operand stack belonging to thread.
Example(s):
onyx:0> self threadostack 1 sprint
(-stack- -stack- -stack- -stack-)
onyx:0>
- threadsdict dict:
Input(s):
None.
Output(s):
dict:
A dictionary. Each key is a thread reference. By default, each value is null, but this need not be so, and the value can be redefined for debugging purposes.
Error(s):
None.
Description:
Get a dictionary containing references to all threads.
Example(s):
onyx:0> threadsdict 1 sprint
<-thread- null>
onyx:0>
name throw obj:
Input(s):
name:
The name of an error.
Output(s):
obj:
The object that was being executed when the error was thrown.
Error(s):
stackunderflow.
typecheck.
undefined.
Description:
Throw an error, using the following steps:
  1. Set newerror in the currenterror dictionary to true.
  2. Set errorname in the currenterror dictionary to name.
  3. Set ostack, dstack, estack, and istack in the currenterror dictionary to be current stack snapshots.
  4. Push the object that was being executed before throw was called onto ostack.
  5. If there is an error handler in the errordict dictionary that corresponds to name, evaluate it. Otherwise, evaluate errordict's handleerror and stop operators.
Example(s):
onyx:0> $unregistered throw
Error $unregistered
ostack: ()
dstack: (-dict- -dict- -dict- -dict-)
cstack: ()
estack/istack trace (0..1):
0:      -file-
1:      --start--
onyx:1> pstack
-file-
onyx:1>
condition mutex timeout timedwait boolean:
Input(s):
condition:
A condition object.
mutex:
A mutex object that this thread currently owns.
timeout:
Minimum number of nanoseconds to wait for condition.
Output(s):
boolean:
If false, success, otherwise timeout.
Error(s):
stackunderflow.
typecheck.
Description:
Wait on condition for at least timeout nanoseconds. mutex is atomically released when the current thread blocks, then acquired again before the current thread runs again. Using a mutex that the current thread does not own will result in undefined behavior (likely crash).
Example(s):
onyx:0> condition mutex dup lock ostack
onyx:3> {dup lock exch signal unlock}
onyx:4> thread 3 1 roll
onyx:3> dup 3 1 roll
onyx:4> 1000000000 timedwait 1 sprint unlock join
false
onyx:0> mutex condition 1 idup dup lock 1000000000 timedwait 1 sprint unlock
true
onyx:0>
file/string token false:
file/string token file/substring obj true:
Input(s):
file:
A file that is used as onyx source code to scan a token from.
string:
A string that is used as onyx source code to scan a token from.
Output(s):
file:
The same file object that was passed in.
substring:
The remainder of string after scanning a token.
obj:
An object that was constructed by scanning a token.
false/true:
If true, a token was successfully scanned, false otherwise.
Error(s):
stackunderflow.
syntaxerror.
typecheck.
undefined.
Description:
Scan a token from a file or string, using onyx syntax rules. If a token is followed by whitespace, one character of whitespace is consumed when the token is scanned.
Example(s):
onyx:0> `1 2' token pstack clear
true
1
`2'
onyx:0> `foo' token pstack clear
true
foo
`'
onyx:0> `foo ' token pstack clear
true
foo
`'
onyx:0> `foo  ' token pstack clear
true
foo
` '
onyx:0> `foo$bar' token pstack clear
true
foo
`$bar'
onyx:0> `foo{}' token pstack clear
true
foo
`{}'
onyx:0> ` ' token pstack clear
false
onyx:0>
obj trapped false:
obj trapped arg true:
Input(s):
obj:
An object to evaluate.
Output(s):
arg:
The argument that was passed to the escape operator that caused unwinding to this trapped context.
false:
The escape operator was not executed.
true:
The escape operator was executed.
Error(s):
invalidcontinue.
invalidexit.
stackunderflow.
Description:
Evaluate obj. This operator provides a context that snapshots the state of ostack, dstack, and cstack, then restores those snapshotted states if the escape operator causes the execution stack to unwind to the point where trapped was called. It will also terminate execution stack unwinding due to the continue and exit operators, but will throw an invalidcontinue or invalidexit error, respectively, then do the equivalent of calling quit .
Example(s):
onyx:0> {1 2 3 $arg escape} trapped {1 sprint} if
$arg
onyx:0> {1 2 3} trapped {1 sprint}{pstack clear} ifelse
3
2
1
onyx:0>
a trunc r:
Input(s):
a:
An integer or real.
Output(s):
r:
Integer created from a by discarding the fractional portion.
Error(s):
stackunderflow.
typecheck.
Description:
Discard the fractional portion of a to create an integer, and return the result.
Example(s):
onyx:0> -1.51 trunc 1 sprint
-1
onyx:0> -1.49 trunc 1 sprint
-1
onyx:0> 0 trunc 1 sprint
0
onyx:0> 1.49 trunc 1 sprint
1
onyx:0> 1.51 trunc 1 sprint
1
onyx:0>
file length truncate -:
Input(s):
file:
A file object.
length:
New length for file.
Output(s):
None.
Error(s):
ioerror.
rangecheck.
stackunderflow.
typecheck.
Description:
Set the length of file to length. If this causes the file to grow, the appended bytes will have the value zero.
Example(s):
onyx:0> `/tmp/foo' `w+' open
onyx:1> dup `Hello\n' write
onyx:1> dup flushfile
onyx:1> dup 0 seek
onyx:1> dup 10 string read
onyx:3> pop 1 sprint
`Hello\n'
onyx:1> dup 3 truncate
onyx:1> dup 0 seek
onyx:1> dup 10 string read
onyx:3> pop 1 sprint
`Hel'
onyx:1>
- true true:
Input(s):
None.
Output(s):
true:
The boolean value true.
Error(s):
None.
Description:
Return true.
Example(s):
onyx:0> true 1 sprint
true
onyx:0>
mutex trylock boolean:
Input(s):
mutex:
A mutex object.
Output(s):
boolean:
If false, mutex was successfully acquired. Otherwise the mutex acquisition failed.
Error(s):
stackunderflow.
typecheck.
Description:
Try to acquire mutex, but return a failure immediately if mutex cannot be acquired, rather than blocking.
Example(s):
onyx:0> mutex dup
onyx:2> trylock 1 sprint
false
onyx:1> trylock 1 sprint
true
onyx:0>
a b tuck b a b:
Input(s):
a:
An object.
b:
An object.
Output(s):
:
Error(s):
stackunderflow.
typecheck.
Description:
Create a duplicate of the top object on ostack and put it under the second object on ostack.
Example(s):
onyx:0> `a' `b' `c'
oonyx:3> tuck pstack
`c'
`b'
`c'
`a'
onyx:4>
obj type name:
Input(s):
obj:
An object.
Output(s):
name:
An executable name that corresponds to the type of obj:
array:
arraytype.
boolean:
booleantype.
condition:
conditiontype.
dict:
dicttype.
file:
filetype.
fino:
finotype.
handle:
handletype.
integer:
integertype.
mark:
marktype.
mutex:
mutextype.
name:
nametype.
null:
nulltype.
operator:
operatortype.
pmark:
pmarktype.
stack:
stacktype.
string:
stringtype.
thread:
threadtype.
Error(s):
stackunderflow.
Description:
Get a name that represent the type of obj.
Example(s):
onyx:0> true type 1 sprint
booleantype
onyx:0>
- uid uid:
Input(s):
None.
Output(s):
uid:
Process's user ID.
Error(s):
None.
Description:
Get the process's user ID.
Example(s):
onyx:0> uid 1 sprint
1001
onyx:0>
nmask umask omask:
Input(s):
nmask:
Value to set umask to.
Output(s):
omask:
Old umask.
Error(s):
stackunderflow.
typecheck.
Description:
Set the process's umask to nmask and return the old umask.
Example(s):
onyx:0> 8@777 umask <$b 8 $w 3 $p `0'> output `\n' print flush
022
onyx:0>
dict key undef -:
Input(s):
dict:
A dictionary.
val:
A key in dict to undefine.
Output(s):
None
Error(s):
stackunderflow.
typecheck.
Description:
If key is defined in dict, undefine it.
Example(s):
onyx:0> $foo `foo' def
onyx:0> currentdict $foo undef
onyx:0> currentdict $foo undef
onyx:0>
a b under a a b:
Input(s):
a:
An object.
b:
An object.
Output(s):
a:
An object.
b:
An object.
Error(s):
stackunderflow.
Description:
Create a duplicate of the second object on ostack and put it under the top object on ostack.
Example(s):
onyx:0> 0 1 2 under pstack
2
1
1
0
onyx:4>
boolean obj unless -:
Input(s):
boolean:
A boolean.
obj:
An object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Evaluate obj unless boolean is true.
Example(s):
onyx:0> false {`yes' 1 sprint} unless
`yes'
onyx:0> true {`yes' 1 sprint} unless
onyx:0>
filename unlink -:
Input(s):
filename:
A string that represents a filename.
Output(s):
None.
Error(s):
invalidfileaccess.
ioerror.
stackunderflow.
typecheck.
undefinedfilename.
unregistered.
Description:
Unlink filename.
Example(s):
onyx:0> `/tmp/foo' `w' open
onyx:1> dup `Hello\n' write
onyx:1> dup flushfile
onyx:1> close
onyx:0> `/tmp/foo' unlink
onyx:0> `/tmp/foo' `r' open
Error $invalidfileaccess
ostack: (`/tmp/foo' `r')
dstack: (-dict- -dict- -dict- -dict-)
cstack: ()
estack/istack trace (0..2):
0:      --open--
1:      -file-
2:      --start--
onyx:3>
mutex unlock -:
Input(s):
mutex:
A mutex object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Unlock mutex. Unlocking a mutex that the running thread does not own will result in undefined behavior (likely crash).
Example(s):
onyx:0> mutex dup lock unlock
onyx:0>
key unsetenv -:
Input(s):
key:
A name object.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Unset key in the environment and in the envdict dictionary, if key is defined.
Example(s):
onyx:0> $foo `foo' setenv
onyx:0> envdict $foo known 1 sprint
true
onyx:0> envdict $foo get 1 sprint
`foo'
onyx:0> $foo unsetenv
onyx:0> envdict $foo known 1 sprint
false
onyx:0>
proc cond until -:
Input(s):
proc:
An object to be repeatedly evaluated.
cond:
An object that, when evaluated, places a boolean on ostack.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Repeatedly evaluate proc and cond, terminating the first time that cond places false on ostack. This operator supports the continue and exit operators.
Example(s):
onyx:0> 0 {inc dup 1 sprint}{dup 3 lt} until pop
1
2
3
onyx:0> 0 {inc dup 1 sprint exit}{dup 3 lt} until pop
1
onyx:0>
a b c up c a b:
Input(s):
a:
An object.
b:
An object.
c:
An object.
Output(s):
c:
An object.
a:
An object.
b:
An object.
Error(s):
stackunderflow.
Description:
Rotate the top three objects on ostack up one position.
Example(s):
onyx:0> `a' `b' `c' `d' up pstack
`c'
`b'
`d'
`a'
onyx:4>
- userdict dict:
Input(s):
None.
Output(s):
dict:
A dictionary.
Error(s):
None.
Description:
Get userdict. See Section 2.11.12 for details on userdict.
Example(s):
onyx:0> userdict 1 sprint
<>
onyx:0>
- vclass class:
Input(s):
None.
Output(s):
dict:
A class.
Error(s):
None.
Description:
Get vclass. See Section 2.12.1 for details on vclass.
Example(s):
onyx:0> vclass 1 sprint
-class-
onyx:0>
- version string:
Input(s):
None.
Output(s):
string:
A string that contains the version name.
Error(s):
None.
Description:
Get the version string. The string returned is a reference to the original version string.
Example(s):
onyx:0> version pstack
`1.0.0'
onyx:1>
condition mutex wait -:
Input(s):
condition:
A condition object.
mutex:
A mutex object that this thread currently owns.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Wait on condition. mutex is atomically released when the current thread blocks, then acquired again before the current thread runs again. Using a mutex that the current thread does not own will result in undefined behavior (likely crash).
Example(s):
onyx:0> condition mutex dup lock ostack
onyx:3> {dup lock exch signal unlock}
onyx:4> thread 3 1 roll
onyx:3> dup 3 1 roll
onyx:4> wait unlock join
onyx:0>
pid waitpid status:
Input(s):
pid:
Process identifier.
Output(s):
status:
Exit code of terminated process. A negative value indicates that the process was terminated by a signal (use the neg operator to get the signal number), and a non-negative value is the exit code of a program that terminated normally.
Error(s):
stackunderflow.
typecheck.
Description:
Wait for the process with process ID pid to exit.
Example(s):
onyx:0> [`/bin/date'] forkexec dup 1 sprint waitpid 1 sprint
6516
Sat Jul 13 20:47:54 PDT 2002
0
onyx:0>
key where false:
key where dict true:
Input(s):
key:
A key to search for in dstack.
Output(s):
dict:
The topmost dictionary in dstack that contains a definition for key.
false/true:
If false, no definition of key was found in dstack. Otherwise dict is the topmost dictionary in dstack that contains a definition for key.
Error(s):
stackunderflow.
Description:
Get the topmost dictionary in dstack that defines key.
Example(s):
onyx:0> $foo where pstack clear
false
onyx:0> $threaddict where pstack clear
true
<$threaddict -dict- $userdict -dict- $currenterror -dict- $errordict -dict-
$resume -array->
onyx:0>
cond proc while -:
Input(s):
cond:
An object that, when evaluated, places a boolean on ostack.
proc:
An object to be repeatedly evaluated.
Output(s):
None.
Error(s):
stackunderflow.
typecheck.
Description:
Repeatedly evaluate cond and proc, terminating the first time that cond places false on ostack. This operator supports the continue and exit operators.
Example(s):
onyx:0> 0 {dup 3 lt}{inc dup 1 sprint} while pop
1
2
3
onyx:0> 0 {dup 3 lt}{inc dup 1 sprint exit} while pop
1
onyx:0>
file integer/string write false:
file integer/string write integer/substring true:
Input(s):
file:
A file object.
integer:
An integer that represents an ascii character value.
string:
A string object.
Output(s):
false:
Successful complete write.
integer:
The integer that was passed in.
substring:
The substring of string that was not written.
true:
Successful partial write.
Error(s):
ioerror.
stackunderflow.
typecheck.
Description:
Write integer or string to file. Partial writes can only happen for non-blocking files.
Example(s):
onyx:0> `/tmp/foo' `w+' open
onyx:1> dup `Hello\n' write pop
onyx:1> dup 0 seek
onyx:1> dup readline 1 sprint 1 sprint
false
`Hello'
onyx:1>
obj xcheck boolean:
Input(s):
obj:
An object.
Output(s):
boolean:
True if obj has the executable attribute, false otherwise.
Error(s):
stackunderflow.
Description:
Check obj for executable attribute.
Example(s):
onyx:0> {1 2 3} xcheck 1 sprint
true
onyx:0> [1 2 3] xcheck 1 sprint
false
onyx:0>
obj xecheck boolean:
Input(s):
obj:
An object.
Output(s):
boolean:
True if obj has the executable or evaluable attribute, false otherwise.
Error(s):
stackunderflow.
Description:
Check obj for executable or evaluable attribute.
Example(s):
onyx:0> {1 2 3} xecheck 1 sprint
true
onyx:0> {1 2 3} cve xecheck 1 sprint
true
onyx:0> [1 2 3] xecheck 1 sprint
false
onyx:0>
a b xor r:
Input(s):
a:
An integer or boolean.
b:
The same type as a.
Output(s):
r:
If a and b are integers, their bitwise exclusive or, otherwise their logical exclusive or.
Error(s):
stackunderflow.
typecheck.
Description:
Return the bitwise exclusive or of two integers, or the logical exclusive or of two booleans.
Example(s):
onyx:0> true false xor 1 sprint
true
onyx:0> true true xor 1 sprint
false
onyx:0> 5 3 xor 1 sprint
6
onyx:0>
- yield -:
Input(s):
None.
Output(s):
None.
Error(s):
None.
Description:
Vuluntarily yield the processor, so that another thread or process may be run.
Example(s):
onyx:0> 0 100000 {1 add yield} repeat 1 sprint
100000
onyx:0>


next up previous contents index
Next: 2.11.10 threaddict Up: 2.11 Dictionary reference Previous: 2.11.8 sprintsdict   Contents   Index
Jason Evans 2005-03-16