next up previous contents index
Next: The onyx program Up: Contents Previous: Contents   Contents   Index

Subsections


Onyx Language Reference

Onyx is a stack-based, threaded, interpreted language. Its closest relative is Adobe PostScript, followed by Forth. Experienced PostScript programmers should find most aspects of Onyx familiar, but there are significant differences that will prevent a knowledgeable PostScript programmer from programming in Onyx without first skimming this chapter. This chapter does not assume specific knowledge of other programming languages, so stands as a definitive reference for Onyx.

Onyx is different from most languages in that it is not compiled, but rather consumed. For example, there are mechanisms for creating the equivalent of named procedures that can be called at a later time, but behind the scenes, the code is actually being interpreted as it is scanned in such a way that an executable object is created. As such, Onyx is not suited for compilation, native or byte code. However, the language syntax is very simple and the scanner/parser is extremely fast. There is also a mechanism for binding procedures, which makes interpreter performance approximately the same as would be expected of a byte code interpreter.

Onyx is implemented as a C library that can be embedded in other programs. Mechanisms are provided for extending the set of operators available. This manual only documents the base language; see application-specific documentation for any language extensions.

Following is a list of basic language features that are discussed in more detail later in this chapter:


Objects

An Onyx object has three aspects: type, attribute, and value.

Objects fall into two categories according to type: simple and composite. A simple object takes up no memory of its own; it uses space within a stack, array, or dictionary. A composite object requires space of its own in addition to the space taken up in stacks, arrays, or dictionaries to refer to the composite object. See Table 1.1 for object type classifications.


Table 1.1: Simple and composite types
Simple Composite
boolean array
fino condition
integer dict
mark file
name hook
null mutex
operator stack
pmark string
  thread


There can be multiple references that refer to the same memory backing composite objects. In most cases, composite objects that refer to the same memory are indistinguishable, but for arrays and strings, composite objects may only be able to access a subset of the total memory backing them. This behavior is described in detail later.

All objects have a literal, executable, or evaluatable attribute associated with them. Composite objects each have their own attribute, even for composite objects that share the same backing memory. Objects are ``interpreted'' when they are encountered directly by the interpreter. Objects can also be ``evaluated''. One of two actions is taken when an object is interpreted or evaluated:

Table 1.2 enumerates under what circumstances object interpretation results in execution. Table 1.3 enumerates under what circumstances object evaluation results in execution. Note that executable arrays are the only objects that behave differently when interpreted versus evaluated.

In practice, attributes are only useful for types that can be executed. Attributes are not considered in equality test operations.


Table 1.2: Interpretation of objects by type and attribute
Type Attribute
  literal executable evaluatable
array data data code
boolean data data data
condition data data data
dict data data data
file data code code
fino data data data
hook data code code
integer data data data
mark data data data
mutex data data data
name data code code
null data code code
operator data code code
pmark data data data
stack data data data
string data code code
thread data data data



Table 1.3: Evaluation of objects by type and attribute
Type Attribute
  literal executable evaluatable
array data code code
boolean data data data
condition data data data
dict data data data
file data code code
fino data data data
hook data code code
integer data data data
mark data data data
mutex data data data
name data code code
null data code code
operator data code code
pmark data data data
stack data data data
string data code code
thread data data data


array:
An array is an ordered sequence of objects of any type. The sequence of objects contained in an array is indexed starting at 0. References to existing arrays may be constructed such that a contiguous subsequence is visible. The following code creates such an array:

[0 1 2 3 4]
1 3 getinterval

After the code executes, the array left on the operand stack looks like:

[1 2 3]

Executable arrays are in effect procedures. When an array is executed, its elements are sequentially interpreted.

boolean:
A boolean can have two values: true or false.

condition:
A condition is used for thread synchronization. The standard operations on a condition are to wait and to signal.

dict:
A dict (short for dictionary) is a collection of key/value pairs. Other names for dictionaries include ``associative array'' and ``hash''. A key can be of any type, though in most cases, keys are of type name. A value can also be of any type.

file:
A file is a handle to an ordered sequence of bytes with a current position. Read and write permissions are set when a file object is created.

When an executable file is executed, it is used as a source of Onyx code. Data are sequentially read from the file and interpreted until the end of the file is reached.

fino:
A fino (first in, never out) is used as a stack marker when constructing stacks.

hook:
The hook type is not used by the core Onyx language. It can be used by applications that extend the interpreter as a container object. Hooks can be executed, but the results are application dependent.

Each hook has a tag associated with it that can used by C extension code as a form of type checking. By default, the tag is a null object. In most cases, an application that extends the interpreter using hook objects will set hook tags to be name objects.

integer:
An integer is a signed integer in the range $-2^{63}$ to $2^{63} - 1$.

mark:
A mark is used as a stack marker for various stack operations.

mutex:
A mutex is a mutual exclusion lock. Mutexes cannot be acquired recursively, and the application must take care to unlock mutexes before allowing them to be garbage collected (whether during normal program execution or at program termination).

name:
A name is a key that uniquely identifies a sequence of characters. Two name objects that correspond to the same sequence of characters can be compared for equality with the same approximate cost as comparing two integers for equality. Names are typically used as keys in dictionaries.

When an executable name is executed, the topmost value in the dictionary stack associated with the name is evaluated.

null:
A null has no significance other than its existence. When an executable null is executed, it does nothing. Executable nulls can be useful as place holders that can later be replaced with useful code, or for replacing obsolete code so that the code is no longer executed.

operator:
An operator is an operation that is built in to the interpreter. Operators can be executed.

pmark:
A pmark is used as a stack marker when creating procedures in deferred execution mode (i.e. procedures that use the {} syntax). The application will only encounter pmarks in error conditions, and there is never a reason for an application to explicitly create a pmark.

stack:
A stack provides LIFO (last in, first out) access to objects that it contains, as well as some more advanced access methods. An application can create, then manipulate stacks in much the same way that the operand stack can be manipulated.

string:
A string is an ordered sequence of 8 bit characters. The bytes contained in an string are indexed starting at 0. References to existing strings may be constructed such that a contiguous subsequence is visible. The following code creates such a string:

`abcde'
1 3 getinterval

After the code executes, the string left on the operand stack looks like:

`bcd'

When an executable string is executed, its contents are used as a source of Onyx code.

thread:
A thread object serves as a handle for operations such as detaching and joining.


Syntax

Onyx's syntax is very simple in comparison to most languages. The scanner and parser are implemented as a human-understandable finite state machine (nested C switch statements with a couple of auxiliary variables), which should give the reader an idea of the simplicity of the language syntax.

CRNL (carriage return, newline) pairs are in all important cases converted to newlines during scanning.

The characters %, /, [, ], {, }, (, ), `, ', <, and > are special. In most cases, any of the special characters and whitespace (space, tab, newline, formfeed, null) terminate any preceding token. All other characters including non-printing characters are considered regular characters.

A comment starts with a % character outside of a string context and extends to the next newline or formfeed.

Procedures are actually executable arrays, but Onyx provides special syntax for declaring procedures. Procedures are delimited by { and }, and can be nested. Normally, the interpreter executes code as it is scanned, but inside of procedure declarations, execution is deferred. Instead of executing a procedure body as it is encountered, the tokens of the procedure body are pushed onto the operand stack until the closing } is encountered, at which time an executable array is constructed from the tokens in the procedure body and pushed onto the operand stack.

A partial grammar specification, using BNF notation (where convenient) is as follows:

<program> ::=
<statement>

<statement> ::=
<procedure> <statement> | <object> <statement> | $\epsilon$

<procedure> ::=
{<statement>}

<object> ::=
<integer> | <name> | <string>

<integer> ::=
<dec_integer> | <radix_integer>

<name> :
Any token that cannot be interpreted as a number or a string is interpreted as an executable name. There are three syntaxes for names: executable, literal and immediately evaluated. Executable names are looked up in the dictionary stack and executed (unless execution is deferred). Literal names are simply pushed onto the operand stack. Immediately evaluated names are replaced by their values as defined in the dictionary stack, even if execution is deferred. Examples include:
foo     % executable
4noth3r % executable
/bar    % literal
//biz   % immediately evaluated

If the result of an immediately evaluated name is an executable array, the evaluatable attribute is set for the array so that when the array is interpreted, it is executed. This allows immediate evaluation to be indiscriminately used without concern for whether the result is an executable array or, say, an executable operator.

<string> ::=
`'-delimited string. Ticks may be embedded in the string without escaping them, as long as the unescaped ticks are balanced. The following sequences have special meaning when escaped by a \ character:
`
` character.
'
' character.
\
\ character.
n
Newline.
r
Carriage return.
t
Tab.
b
Backspace.
f
Formfeed.
x[0-9a-fA-F][0-9a-fA-F]
Hex encoding for a byte.
\n (newline)
Ignore.
\r\n (carriage return, newline)
Ignore.

\ has no special meaning unless followed by a character in the above list.

Examples include:

`'
`A string.'
`An embedded \n newline.'
`Another embedded 
newline.'
`An ignored \
newline.'
`Balanced ` and ' are allowed.'
`Manually escaped \` tick.'
`Manually escaped \` tick and `balanced unescaped ticks'.'
`An actual \\ backslash.'
`Another actual \ backslash.'

<dec_integer> :
Signed integer in the range $-2^{63}$ to $2^{63} - 1$. The sign is optional. Examples include:
0
42
-365
+17

<radix_integer> :
Signed integer with explicit base between 2 and 36, inclusive, in the range $-2^{63}$ to $2^{63} - 1$. Integer digits are composed of decimal numbers and lower or upper case letters. The sign is optional. Examples include:
2#101
16#ff
16#Ff
16#FF
-10#42
10#42
+10#42
9#18
35#7r3x
35#7R3x

Arrays do not have explicit syntactic support, but the [ and ] operators support their construction. Examples of array construction include:

[]
[0 `A string' `Another string.' true]
[5
42
false]

Dictionaries do not have explicit syntactic support, but the < and > operators support their construction. Examples of dictionary construction include:

<>
</answer 42 /question `Who knows' /translate {babelfish} >

Stacks do not have explicit syntactic support, but the ( and ) operators support their construction. Examples of stack contstruction include:

()
(1 2 mark `a')

Stacks

Stacks in Onyx are the core data structure that programs act on. Stacks store objects in a last in, first out (LIFO) order. Onyx includes a number of operators that manipulate stacks.

Each Onyx thread has four program-visible stacks associated with it:

Operand stack (ostack):
Most direct object manipulations are done using the operand stack. Operators use the operand stack for inputs and outputs, and code generally uses the operand stack for a place to store objects as they are being manipulated.
Dictionary stack (dstack):
The dictionary stack is used for looking up names. Each thread starts with with four dictionaries on its dictionary stack, which are, from top to bottom: The dictionary stack is manipulated via the begin and end operators. The initial dictionaries on the dictionary stack cannot be removed.
Execution stack (estack):
The interpreter uses the execution stack to store objects that are being executed. The application generally does not need to explicitly manipulate the execution stack, but its contents are accessible, mainly for debugging purposes.
Index stack (istack):
The interpreter uses the index stack to store execution offsets for arrays that are being executed. There is a one to one correspondence of the elements of the execution stack to the elements of the index stack, even though the elements of the index stack that do not correspond to arrays have no meaning. The index stack does not affect execution, and exists purely to allow useful execution stack traces when errors occur.

The application can also create additional stacks and manipulate them in much the same way as the operand stack can be manipulated.

Interpreter recursion

During typical Onyx interpreter initialization, the start operator is executed, which in turn executes a file object corresponding to stdin. However, depending on how the interpreter is invoked, the initial execution stack state may differ.

The interpreter can be recursively invoked. For example, if the following code is executed, the eval operator recursively invokes the interpreter to interpret the string.

`2 2 add' cvx eval

The depth of the execution stack directly corresponds to the recursion depth of the interpreter. Execution stack depth is limited in order to catch unbounded recursion.

Onyx converts tail calls in order to prevent unbounded execution stack growth due to tail recursion. For example, the following code does not cause the execution stack to grow:

/foo {foo} def
foo

The following code will result in an execution stack overflow:

/foo {foo `filler'} def
foo

Error handling

The error handling mechanisms in Onyx are simple but flexible. When an error occurs, the following operations are performed as a result of executing throw :

  1. Store a snapshot of the thread state in the currenterror dictionary.
  2. Push the object whose execution caused the error onto the operand stack.
  3. Find an error handler in errordict corresponding to the current error.
  4. Execute the error handler. The standard error handlers in turn execute errordict's handleerror .
  5. Execute errordict's stop operator.

The Onyx scanner handles syntax errors specially, in that it pushes an executable string onto the operand stack that represents the code that caused the syntax error and records the line and column numbers in currenterror before invoking throw .

The Onyx scanner also handles immediate name evaluation errors specially, in that it pushes the name that could not be evaluated onto ostack before invoking throw .

Threads

Onyx supports multiple threads of execution by using the operating system's native threading facilities. Along with threads comes the need for methods of synchronization between threads.


Implicit synchronization

Implicit synchronization is a mandatory language feature, since objects such as globaldict are implicitly accessed by the interpreter, which makes it impossible to require the user to explicitly handle all synchronization. Onyx provides optional implicit synchronization capabilities for composite objects on an object by object basis. Each thread has a setting which can be accessed via currentlocking (initially set to false) and set via setlocking . If implicit locking is active, then new objects will be created such that simple accesses are synchronized.

Implicit synchronization can be a source of deadlock, so care must be taken when accessing implicitly locked objects. For example, if two threads copy two implicitly locked strings to the other string, deadlock can result.

% Initialization.
/A `aaaaaa'
/B `bbbbbb'

...

% In thread A:
A B copy

...

% In thread B:
B A copy

The following are descriptions of the implicit locking semantics for each type of composite object:

array:
Array copying is protected. Array element modifications are protected, but element reads are not protected.
condition:
No implicit locking is done for conditions.
dict:
All dict operations are protected.
file:
All file operations are protected. There are no potential deadlocks due to implicit file locking.
hook:
No implicit locking is done for hooks.
mutex:
No implicit locking is done for mutexes.
stack:
All stack operations are protected. There are no potential deadlocks due to implicit stack locking. However, there are races in stack copying, such that the results of copying a stack that is concurrently being modified are unpredictable. In addition, removing an object that is being concurrently accessed from a stack is unsafe.
string:
String copying is protected. Character access is protected by many operators, but string copying is the only potential cause of deadlock for string access.
thread:
Implicit locking is not done for thread operations, since other synchronization is adequate to protect thread objects.

Explicit synchronization

Onyx includes a foundation of mutexes and condition variables, with which all other synchronization primitives can be constructed.

Memory management

Onyx programs do not need to track memory allocations, since memory reclamation is done implicitly via automatic garbage collection. Onyx uses an atomic mark and sweep garbage collector.

The atomic nature of garbage collection may sound worrisome with regard to performance, but in fact there are tangible benefits and no significant negative impacts for most applications. Total throughput is improved, since minimal locking is necessary. Concurrent garbage collection would impose a significant locking overhead.

On the down side, atomic garbage collection cannot make strong real-time guarantees. However, the garbage collector is very efficient, and for typical applications, garbage collection delays are measured in microseconds up to tens of milliseconds on current hardware as of the year 2000. For interactive applications, anything under about 100 milliseconds is undetectable by the user, so under normal circumstances the user will not notice that garbage collection is happening.

There are three parameters that can be used to control garbage collection:

  1. The garbage collector can be turned off for situations where many objects are being created over a short period of time.
  2. The garbage collector runs whenever a certain number of bytes of memory have been allocated since the last collection. This threshold can be changed or disabled.
  3. If no composite objects have been created for an extended period of time (seconds), the garbage collector will run if any composite objects have been allocated since the last collection. This idle timeout period can be changed or disabled.

There is one situation in which it is possible for garbage to never be collected, despite the garbage collector being properly configured. Suppose that a program creates some objects, the garbage collector runs, then the program enters a code path that clobbers object references, such that the objects could be collected, but no new objects are allocated. In such a situation, neither the allocation inactivity timer (period), nor the object allocation threshold will trigger a collection, and garbage will remain uncollected. In practice this situation is unlikely, and is not a significant problem since the program size is not growing.

Garbage collection is controlled via the gcdict dictionary, which is described in Section 1.8.4.

Dictionary reference

All operators built in to Onyx have corresponding names that are composed entirely of lower case letters. In order to avoid any possibility of namespace collisions with names defined by current and future versions of Onyx, use at least one character that is not a lower case letter in names (for example, capital letters, numbers, underscore, etc.).


currenterror

Each thread has its own currenterror dictionary, which is used by the error handling machinery to store error state.

Table 1.4: currenterror summary
Input(s) Op/Proc/Var Output(s) Description
- newerror boolean Set to true during error handling.
- errorname name Name of most recent error.
- line number Get line number of syntax error.
- column number Get column number of syntax error.
- ostack stack ostack snapshot.
- dstack stack dstack snaphot.
- estack stack estack snapshot.
- istack stack istack snapshot.

- column integer:
Input(s):
None.
Output(s):
integer:
Column number, valid only if the error was a syntaxerror. Column numbering starts at 0.
Errors(s):
None.
Description:
Get the column number that a syntaxerror occurred on.
Example(s):
onyx:0> `1 2 3}' cvx eval
At line 1, column 5: Error /syntaxerror
ostack: (1 2 3 `}')
dstack: (-dict- -dict- -dict- -dict-)
estack/istack trace (0..3):
0:      `1 2 3}'
1:      --eval--
2:      -file-
3:      --start--
onyx:5> currenterror /column get 1 sprint
5
onyx:5>
- dstack stack:
Input(s):
None.
Output(s):
stack:
A dstack snapshot.
Errors(s):
None.
Description:
Get a stack that is a dstack snapshot as of the most recent error.
Example(s):
onyx:0> x
Error /undefined
ostack: ()
dstack: (-dict- -dict- -dict- -dict-)
estack/istack trace (0..2):
0:      x
1:      -file-
2:      --start--
onyx:1> currenterror begin dstack end 1 sprint
(-dict- -dict- -dict- -dict-)
onyx:1>
- errorname name:
Input(s):
None.
Output(s):
name:
Name of the most recent error. The name is usually one of the errors defined in errordict.
Errors(s):
None.
Description:
Get the name of the most recent error.
Example(s):
onyx:0> x
Error /undefined
ostack: ()
dstack: (-dict- -dict- -dict- -dict-)
estack/istack trace (0..2):
0:      x
1:      -file-
2:      --start--
onyx:1> currenterror begin errorname end 1 sprint
/undefined
onyx:1>
- estack stack:
Input(s):
None.
Output(s):
stack:
An estack snapshot.
Errors(s):
None.
Description:
Get a stack that is an estack snapshot as of the most recent error.
Example(s):
onyx:0> x
Error /undefined
ostack: ()
dstack: (-dict- -dict- -dict- -dict-)
estack/istack trace (0..2):
0:      x
1:      -file-
2:      --start--
onyx:1> currenterror begin estack end 1 sprint
(--start-- -file- x)
onyx:1>
- istack stack:
Input(s):
None.
Output(s):
stack:
An istack snapshot.
Errors(s):
None.
Description:
Get a stack that is an istack snapshot as of the most recent error.
Example(s):
onyx:0> x
Error /undefined
ostack: ()
dstack: (-dict- -dict- -dict- -dict-)
estack/istack trace (0..2):
0:      x
1:      -file-
2:      --start--
onyx:1> currenterror begin istack end 1 sprint
(0 0 0)
onyx:1>
- newerror boolean:
Input(s):
None.
Output(s):
boolean:
False if there has been no error since the last time newerror was reset; true otherwise.
Errors(s):
None.
Description:
Get a boolean that represents whether there has been an error since the last time newerror was set to false (as during interpreter initialization). It is the application's responsibility to reset newerror after each error if it expects the value to be useful across multiple errors.
Example(s):
onyx:0> currenterror begin
onyx:0> newerror 1 sprint
false
onyx:0> x
Error /undefined
ostack: ()
dstack: (-dict- -dict- -dict- -dict- -dict-)
estack/istack trace (0..2):
0:      x
1:      -file-
2:      --start--
onyx:1> newerror 1 sprint
true
onyx:1> /newerror false def
onyx:1> newerror 1 sprint
false
onyx:1> resume
onyx:1> y
Error /undefined
ostack: (x)
dstack: (-dict- -dict- -dict- -dict- -dict-)
estack/istack trace (0..2):
0:      y
1:      -file-
2:      --start--
onyx:2> newerror 1 sprint
true
onyx:2>
- line integer:
Input(s):
None.
Output(s):
integer:
Line number, valid only if the error was a syntaxerror. Line numbering starts at 1.
Errors(s):
None.
Description:
Get the line number that a syntaxerror occurred on.
Example(s):
onyx:0> `1 2 3}' cvx eval
At line 1, column 5: Error /syntaxerror
ostack: (1 2 3 `}')
dstack: (-dict- -dict- -dict- -dict-)
estack/istack trace (0..3):
0:      `1 2 3}'
1:      --eval--
2:      -file-
3:      --start--
onyx:5> currenterror /line get 1 sprint
1
onyx:5>
- ostack stack:
Input(s):
None.
Output(s):
stack:
An ostack snapshot.
Errors(s):
None.
Description:
Get a stack that is an ostack snapshot as of the most recent error.
Example(s):
onyx:0> x
Error /undefined
ostack: ()
dstack: (-dict- -dict- -dict- -dict-)
estack/istack trace (0..2):
0:      x
1:      -file-
2:      --start--
onyx:1> currenterror begin ostack end 1 sprint
()
onyx:1>


envdict

The envdict dictionary contains keys of type name and values of type string that correspond to the environment passed into the program. All threads share the same envdict, which is implicitly locked. Modifications to envdict should be made via the setenv and unsetenv operators. If envdict is modified directly, the changes will not be visible to programs such as ps.


errordict

Each thread has its own errordict, which is used by default by the error handling machinery. throw calls the error handlers, which call errordict's handleerror , after which throw calls errordict's stop . Any of the names in errordict can be redefined to suit the thread's or application's error handling requirements.

Table 1.5: errordict summary by functional group
Input(s) Op/Proc/Var Output(s) Description
Control operators
- handleerror - Print a state dump.
- stop - Last operation during error handling.
Error operators
- dstackunderflow - Dictionary stack underflow.
- estackoverflow - Maximum recursion depth exceeded.
- invalidaccess - Permission error.
- invalidexit - Exit outside of any loop.
- invalidfileaccess - Insufficient file permissions.
- ioerror - I/O error.
- limitcheck - Value outside of legal range.
- rangecheck - Out of bounds string or array access.
- stackunderflow - Not enough objects on ostack.
- syntaxerror - Scanner syntax error.
- typecheck - Incorrect argument type.
- undefined - Name not defined in dstack.
- undefinedfilename - Bad filename.
- undefinedresult - Divide by 0.
- unmatchedfino - No fino on ostack.
- unmatchedmark - No mark on ostack.
- unregistered - Non-enumerated error.

- dstackunderflow -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
An attempt was made to remove one of the initial dictionaries from dstack.
- estackoverflow -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
Maximum interpreter recursion was exceeded.
- handleerror -:
Input(s):
None.
Output(s):
None.
Errors(s):
Under normal conditions, no errors occur. However, it is possible for the application to corrupt the error handling machinery to the point that an error will occur. If that happens, the result is possible infinite recursion, and program crashes are a real possibility.
Description:
Print a dump of the most recent error recorded in the currenterror dictionary.
Example(s):
onyx:0> {true {true 1 sprint x y} if} eval
true
Error /undefined
ostack: ()
dstack: (-dict- -dict- -dict- -dict-)
estack/istack trace (0..5):
0:      x
1: {
        true
        1
        sprint
 3:-->  x
        y
}
2:      --if--
3:      --eval--
4:      -file-
5:      --start--
onyx:1> errordict begin handleerror end
Error /undefined
ostack: ()
dstack: (-dict- -dict- -dict- -dict-)
estack/istack trace (0..5):
0:      x
1: {
        true
        1
        sprint
 3:-->  x
        y
}
2:      --if--
3:      --eval--
4:      -file-
5:      --start--
onyx:1>
- invalidaccess -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
Permission error.
- invalidexit -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
Exit was called outside of any loop. This error is generated as a result of catching an exit, so the execution state for where the error really happened is gone.
- invalidfileaccess -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
Insufficient file permissions.
- ioerror -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
I/O error (read(), write(), etc.).
- limitcheck -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
Value outside of legal range.
- rangecheck -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
Out of bounds string or array access.
- stackunderflow -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
Not enough objects on ostack.
- stop -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
This is called as the very last operation when an error occurs. Initially, its value is the same as that for the stop operator in systemdict.
Example(s):
onyx:0> errordict begin
onyx:0> /stop {`Custom stop\n' print flush quit} def
onyx:0> x
Error /undefined
ostack: ()
dstack: (-dict- -dict- -dict- -dict- -dict-)
estack/istack trace (0..2):
0:      x
1:      -file-
2:      --start--
Custom stop
- syntaxerror -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
Scanner syntax error.
- typecheck -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
Incorrect argument type.
- undefined -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
Name not defined in any of the dictionaries on dstack.
- undefinedfilename -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
Bad filename.
- undefinedresult -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
Attempt to divide by 0.
- unmatchedfino -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
No fino on ostack.
- unmatchedmark -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
No mark on ostack.
- unregistered -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
Non-enumerated error.


gcdict

The gcdict dictionary provides garbage collection control and status capabilities.

Table 1.6: gcdict summary by functional group
Input(s) Op/Proc/Var Output(s) Description
Control operators
- collect - Force a garbage collection.
boolean setactive - Set whether the garbage collector is active.
seconds setperiod - Set the inactivity period before the garbage collector will run.
count setthreshold - Set the number of bytes of memory allocation that will trigger a garbage collection.
State and statistics operators
- active boolean Get whether the garbage collector is active.
- period seconds Get the inactivity period befor the garbage collector will run.
- threshold count Get the number of bytes of memory allocation that will trigger a garbage collection.
- stats array Get garbage collection statistics.

- active boolean:
Input(s):
None.
Output(s):
boolean:
If true, the garbage collector is active; otherwise it is not active.
Errors(s):
None.
Description:
Get whether the garbage collector is active.
Example(s):
onyx:0> gcdict begin active end 1 sprint
false
- collect -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
Force a garbage collection.
Example(s):
onyx:0> gcdict begin collect end
onyx:0>
- period seconds:
Input(s):
None.
Output(s):
seconds:
The minimum number of seconds since the last object allocation that the garbage collector will wait before doing a garbage collection. 0 is treated specially to mean forever.
Errors(s):
None.
Description:
Get the minimum number of seconds of object allocation inactivity that the garbage collector will wait before doing a garbage collection. This setting is disjoint from the threshold setting, and does not prevent garbage collection due to the threshold having been reached.
Example(s):
onyx:0> gcdict begin period end 1 sprint
60
onyx:0>
boolean setactive -:
Input(s):
boolean:
If true (initial setting), activate the garbage collector; otherwise deactivate the garbage collector.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Set whether the garbage collector is active. This setting takes effect asynchronously, so it is possible for the garbage collector to run even after it has been deactivated. This setting overrides the allocation inactivity period and allocation threshold settings, so that if this setting is set to false, the other settings have no effect.
Example(s):
onyx:0> gcdict begin false setactive end
onyx:0>
seconds setperiod -:
Input(s):
seconds:
The minimum number of seconds since the last object allocation that the garbage collector will wait before doing a garbage collection. 0 is treated specially to mean forever.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
limitcheck.
Description:
Set the minimum number of seconds of object allocation inactivity that the garbage collector will wait before doing a garbage collection. This setting is disjoint from the threshold setting, and does not prevent garbage collection due to the threshold having been reached.
Example(s):
onyx:0> gcdict begin 60 setperiod end
onyx:0>
count setthreshold -:
Input(s):
count:
Number of bytes of memory allocation since the last garbage collection that will trigger a garbage collection. 0 is treated specially to mean infinity.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
limitcheck.
Description:
Set the number of bytes of memory allocation since the last garbage collection that will trigger a garbage collection. This setting is disjoint from the inactivity period setting, and does not prevent garbage collection due to the allocation inactivity period having been exceeded.
Example(s):
onyx:0> gcdict begin 40000 setthreshold end
onyx:0>
- stats array:
Input(s):
None.
Output(s):
array:
An array with the format [collections count [ccount cmark csweep] [mcount mmark msweep] [scount smark ssweep]], where the fields have the following meanings:
collections:
Total number of collections the garbage collector has performed.
count:
Current number of bytes of memory allocated.
ccount:
Number of bytes of memory allocated as of the end of the most recent garbage collection.
cmark:
Number of microseconds taken by the most recent garbage collection mark phase.
csweep:
Number of microseconds taken by the most recent garbage collection sweep phase.
mcount:
Largest number of bytes of memory ever allocated at any point in time.
mmark:
Maximum number of microseconds taken by any garbage collection mark phase.
msweep:
Number of microseconds taken by any garbage collection sweep phase.
scount:
Total number of bytes of memory ever allocated.
smark:
Total number of microseconds taken by all garbage collection mark phases.
ssweep:
Total number of microseconds taken by all garbage collection sweep phases.
Errors(s):
None.
Description:
Get statistics about the garbage collector.
Example(s):
onyx:0> gcdict begin
onyx:0> stats 2 sprint
[23 72673 [72268 754 3467] [4752223 930 36492] [51057886 17448 136807]]
onyx:0>
- threshold count:
Input(s):
None.
Output(s):
count:
Number of bytes of memory allocation since the last garbage collection that will trigger a garbage collection. 0 is treated specially to mean infinity.
Errors(s):
None.
Description:
Get the number of bytes of memory allocation since the last garbage collection that will trigger a garbage collection. This setting is disjoint from the inactivity period setting, and does not prevent garbage collection due to the allocation inactivity period having been exceeded.
Example(s):
onyx:0> gcdict begin threshold end 1 sprint
65536
onyx:0>


globaldict

All threads share the same globaldict, which is meant as a repository for globally shared objects. globaldict is empty when the Onyx interpreter is initialized, and is implicitly locked.


outputsdict

The outputsdict dictionary is primarily used to support outputs , but its contents may be of use to an application that wishes to extend or modify formatted printing.

There is an entry in outputsdict for each Onyx type. Each entry renders objects that correspond to its name using optional flags stored in a dictionary. The following flags are supported for all types:

/n:
Maximum length, in bytes. Default: disabled.
/w:
Minimum length, in bytes. Default: disabled.
/j:
Justification. Legal values:
/l:
Left.
/c:
Center.
/r:
Right (default).
/p:
Padding character. Default: ` '.
/r:
Syntactic rendering recursion depth. Default: 1.

In addition, the following flags are supported for integers:

/b:
Base, from 2 to 36. Default: 10.
/s:
Sign. Legal values:
/-:
Only print sign if output is negative (default).
/+:
Always print sign.

Table 1.7: outputsdict summary
Input(s) Op/Proc/Var Output(s) Description
array flags arraytype string Create formatted string from array.
boolean flags booleantype string Create formatted string from boolean.
condition flags conditiontype string Create formatted string from condition.
dict flags dicttype string Create formatted string from dict.
file flags filetype string Create formatted string from file.
fino flags finotype string Create formatted string from fino.
hook flags hooktype string Create formatted string from hook.
integer flags integertype string Create formatted string from integer.
mark flags marktype string Create formatted string from mark.
mutex flags mutextype string Create formatted string from mutex.
name flags nametype string Create formatted string from name.
null flags nulltype string Create formatted string from null.
operator flags operatortype string Create formatted string from operator.
pmark flags pmarktype string Create formatted string from pmark.
stack flags stacktype string Create formatted string from stack.
string flags stringtype string Create formatted string from string.
thread flags threadtype string Create formatted string from thread.

array flags arraytype string:
Input(s):
array:
An array object.
flags:
Formatting flags.
Output(s):
string:
Formatted string representation of array.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of array.
Example(s):
onyx:0> outputsdict begin
onyx:0> [1 [2 3] 4]
onyx:1> dup </w 9 /p `_' /r 0> arraytype print `\n' print flush
__-array-
onyx:1> dup </w 9 /p `_' /r 1> arraytype print `\n' print flush
[1 -array- 4]
onyx:1>
boolean flags booleantype string:
Input(s):
boolean:
A boolean object.
flags:
Formatting flags.
Output(s):
string:
Formatted string representation of boolean.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of boolean.
Example(s):
onyx:0> outputsdict begin
onyx:0> false
onyx:1> dup </n 3> booleantype print `\n' print flush
fal
onyx:1> dup </n 7> booleantype print `\n' print flush
false
onyx:1>
condition flags conditiontype string:
Input(s):
condition:
A condition object.
flags:
Formatting flags.
Output(s):
string:
Formatted string representation of condition.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of condition.
Example(s):
onyx:0> outputsdict begin
onyx:0> condition
onyx:1> </w 15 /p `_' /j /c> booleantype print `\n' print flush
__-condition-__
onyx:0>
dict flags dicttype string:
Input(s):
dict:
A dict object.
flags:
Formatting flags.
Output(s):
string:
Formatted string representation of dict.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of dict.
Example(s):
onyx:0> outputsdict begin
onyx:0> </foo `foo'> </w 30 /p `.' /j /r> dicttype print `\n' print flush
..................</foo `foo'>
onyx:0>
file flags filetype string:
Input(s):
file:
A file object.
flags:
Formatting flags.
Output(s):
string:
Formatted string representation of file.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of file.
Example(s):
onyx:0> outputsdict begin
onyx:0> stdin
onyx:1> </w 30 /p `.' /j /c> filetype print `\n' print flush
............-file-............
onyx:0>
fino flags finotype string:
Input(s):
fino:
A fino object.
flags:
Formatting flags.
Output(s):
string:
Formatted string representation of fino.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of fino.
Example(s):
onyx:0> outputsdict begin
onyx:0> (
onyx:1> </w 30 /p `.' /j /c> finotype print `\n' print flush
............-fino-............
onyx:0>
hook flags hooktype string:
Input(s):
hook:
A hook object.
flags:
Formatting flags.
Output(s):
string:
Formatted string representation of hook.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of hook.
Example(s):
The following example is a bit contrived, since there is no way to create a hook object with a stock onyx interpreter. Therefore, imagine that an operator named taggedhook exists that creates a hook with a tag that is the name ``tagged''.
onyx:0> outputsdict begin
onyx:0> taggedhook
onyx:1> </w 30 /p `.' /j /l hooktype print `\n' print flush
=tagged=......................
onyx:0>
integer flags integertype string:
Input(s):
integer:
An integer object.
flags:
Formatting flags.
Output(s):
string:
Formatted string representation of integer.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of integer.
Example(s):
onyx:0> outputsdict begin
onyx:0> 42 </w 6 /p `_' /j /c /s /-> integertype print `\n' print flush
__42__
onyx:0> 42 </w 6 /p `_' /j /c /s /+> integertype print `\n' print flush
_+42__
onyx:0> `0x' print 42 </w 6 /p `0' /b 16> integertype print `\n' print flush
0x00002a
onyx:0>
mark flags marktype string:
Input(s):
mark:
A mark object.
flags:
Formatting flags.
Output(s):
string:
Formatted string representation of mark.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of mark.
Example(s):
onyx:0> outputsdict begin
onyx:0> mark
onyx:1> </w 30 /p `.' /j /c> marktype print `\n' print flush
............-mark-............
onyx:0>
mutex flags mutextype string:
Input(s):
mutex:
A mutex object.
flags:
Formatting flags.
Output(s):
string:
Formatted string representation of mutex.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of mutex.
Example(s):
onyx:0> outputsdict begin
onyx:0> mutex
onyx:1> </w 30 /p `.' /j /c> mutextype print `\n' print flush
...........-mutex-............
onyx:0>
name flags nametype string:
Input(s):
name:
A name object.
flags:
Formatting flags.
Output(s):
string:
Formatted string representation of name.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of name.
Example(s):
onyx:0> outputsdict begin
onyx:0> /foo
onyx:1> </w 30 /p `.' /j /c> nametype print `\n' print flush
............./foo.............
onyx:0>
null flags nulltype string:
Input(s):
null:
A null object.
flags:
Formatting flags.
Output(s):
string:
Formatted string representation of null.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of null.
Example(s):
onyx:0> outputsdict begin
onyx:0> null
onyx:1> </w 30 /p `.' /j /c> nulltype print `\n' print flush
.............null.............
onyx:0>
operator flags operatortype string:
Input(s):
operator:
An operator object.
flags:
Formatting flags.
Output(s):
string:
Formatted string representation of operator.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of operator.
Example(s):
The following example shows an operator printed out with two leading and trailing dashes. If the interpreter cannot determine the name associated with an operator, as will be the case for custom operators, the operator will be printed as -operator-.
onyx:0> outputsdict begin
onyx:0> //realtime
onyx:1> </w 30 /p `.' /j /c> operatortype print `\n' print flush
.........--realtime--.........
onyx:0>
pmark flags pmarktype string:
Input(s):
pmark:
A pmark object.
flags:
Formatting flags.
Output(s):
string:
Formatted string representation of pmark.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of pmark.
Example(s):
onyx:0> outputsdict begin
onyx:0> { //x
Error /undefined
ostack: (-pmark- /x)
dstack: (-dict- -dict- -dict- -dict- -dict-)
estack/istack trace (0..1):
0:      -file-
1:      --start--
onyx:3> pop pop resume
onyx:1> </w 30 /p `.' /j /c> pmarktype print `\n' print flush
...........-pmark-............
onyx:0>
stack flags stacktype string:
Input(s):
stack:
A stack object.
flags:
Formatting flags.
Output(s):
string:
Formatted string representation of stack.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of stack.
Example(s):
onyx:0> outputsdict begin
onyx:0> (1 (2 3) 4)
onyx:1> dup </w 9 /p `_' /r 0> stacktype print `\n' print flush
__-stack-
onyx:1> </w 9 /p `_' /r 1> stacktype print `\n' print flush
(1 -stack- 4)
onyx:0>
string flags stringtype string:
Input(s):
string:
A string object.
flags:
Formatting flags.
Output(s):
string:
Formatted string representation of string.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of string.
Example(s):
onyx:0> outputsdict begin
onyx:0> `A string'
onyx:1> </w 30 /p `.' /j /c> stringtype print `\n' print flush
...........A string...........
onyx:0>
thread flags threadtype string:
Input(s):
thread:
A thread object.
flags:
Formatting flags.
Output(s):
string:
Formatted string representation of thread.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of thread.
Example(s):
onyx:0> outputsdict begin
onyx:0> () {} thread
onyx:1> </w 30 /p `.' /j /c> threadtype print `\n' print flush
...........-thread-...........
onyx:0>


sprintsdict

The sprintsdict dictionary is primarily used to support sprints , but its contents may be of use to an application that wishes to extend or modify syntactical printing.

There is an entry in sprintsdict for each Onyx type. If there is a syntactically valid representation for an object and the recursion depth is greater than 0, the corresponding operator creates a string that syntactically represents the object. Otherwise, a string with a non-syntictical representation of the object is created, except for booleans, integers, names, nulls, and strings, for which the results are always syntactical. If the recursion depth is greater than 0, the operators will recursively convert any contained objects.

The implementation of sprints is useful in illustrating a useful method of doing type-dependent operations:

/sprints {
        1 index type /sprintsdict load exch get eval
} def

Table 1.8: sprintsdict summary
Input(s) Op/Proc/Var Output(s) Description
array depth arraytype string Create syntactical string from array.
boolean depth booleantype string Create syntactical string from boolean.
condition depth conditiontype string Create syntactical string from condition.
dict depth dicttype string Create syntactical string from dict.
file depth filetype string Create syntactical string from file.
fino depth finotype string Create syntactical string from fino.
hook depth hooktype string Create syntactical string from hook.
integer depth integertype string Create syntactical string from integer.
mark depth marktype string Create syntactical string from mark.
mutex depth mutextype string Create syntactical string from mutex.
name depth nametype string Create syntactical string from name.
null depth nulltype string Create syntactical string from null.
operator depth operatortype string Create syntactical string from operator.
pmark depth pmarktype string Create syntactical string from pmark.
stack depth stacktype string Create syntactical string from stack.
string depth stringtype string Create syntactical string from string.
thread depth threadtype string Create syntactical string from thread.

array depth arraytype string:
Input(s):
array:
An array object.
depth:
Recursion depth.
Output(s):
string:
Syntactical string representation of array.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of array.
Example(s):
onyx:0> sprintsdict begin
onyx:0> [1 [2 3] 4]
onyx:1> dup 0 arraytype print `\n' print flush
-array-
onyx:1> dup 1 arraytype print `\n' print flush
[1 -array- 4]
onyx:1> dup 2 arraytype print `\n' print flush
[1 [2 3] 4]
onyx:1>
boolean depth booleantype string:
Input(s):
boolean:
A boolean object.
depth:
Recursion depth.
Output(s):
string:
Syntactical string representation of boolean.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of boolean.
Example(s):
onyx:0> sprintsdict begin
onyx:0> true
onyx:1> dup 0 booleantype print `\n' print flush
true
onyx:1>
condition depth conditiontype string:
Input(s):
condition:
A condition object.
depth:
Recursion depth.
Output(s):
string:
Syntactical string representation of condition.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of condition.
Example(s):
onyx:0> sprintsdict begin
onyx:0> condition
onyx:1> dup 0 conditiontype print `\n' print flush
-condition-
onyx:1> dup 1 conditiontype print `\n' print flush
-condition-
onyx:1>
dict depth dicttype string:
Input(s):
dict:
A dict object.
depth:
Recursion depth.
Output(s):
string:
Syntactical string representation of dict.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of dict.
Example(s):
onyx:0> sprintsdict begin
onyx:0> </a `a' /subdict </b `b'>>
onyx:1> dup 0 dicttype print `\n' print flush
-dict-
onyx:1> dup 1 dicttype print `\n' print flush
</subdict -dict- /a `a'>
onyx:1> dup 2 dicttype print `\n' print flush
</subdict </b `b'> /a `a'>
onyx:1>
file depth filetype string:
Input(s):
file:
A file object.
depth:
Recursion depth.
Output(s):
string:
Syntactical string representation of file.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of file.
Example(s):
onyx:0> sprintsdict begin
onyx:0> stdout
onyx:1> dup 0 filetype print `\n' print flush
-file-
onyx:1> dup 1 filetype print `\n' print flush
-file-
onyx:1>
fino depth finotype string:
Input(s):
fino:
A fino object.
depth:
Recursion depth.
Output(s):
string:
Syntactical string representation of fino.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of fino.
Example(s):
onyx:0> sprintsdict begin
onyx:0> (
onyx:1> dup 0 finotype print `\n' print flush
-fino-
onyx:1> dup 1 finotype print `\n' print flush
-fino-
onyx:1>
hook depth hooktype string:
Input(s):
hook:
A hook object.
depth:
Recursion depth.
Output(s):
string:
Syntactical string representation of hook.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of hook.
Example(s):
The following example is a bit contrived, since there is no way to create a hook object with a stock onyx interpreter. Therefore, imagine that an operator named taggedhook exists that creates a hook with a tag that is the name ``tagged'', and that an operator named untaggedhook exists that creates an untagged hook.
onyx:0> sprintsdict begin
onyx:0> taggedhook
onyx:1> dup 0 hooktype print `\n' print flush
=tagged=
onyx:1> 1 hooktype print `\n' print flush
=tagged=
onyx:0> untaggedhook
onyx:1> dup 0 hooktype print `\n' print flush
-hook-
onyx:1> 1 hooktype print `\n' print flush
-hook-
onyx:0>
integer depth integertype string:
Input(s):
integer:
An integer object.
depth:
Recursion depth.
Output(s):
string:
Syntactical string representation of integer.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of integer.
Example(s):
onyx:0> sprintsdict begin
onyx:0> 42
onyx:1> dup 0 integertype print `\n' print flush
42
onyx:1> dup 1 integertype print `\n' print flush
42
onyx:1>
mark depth marktype string:
Input(s):
mark:
A mark object.
depth:
Recursion depth.
Output(s):
string:
Syntactical string representation of mark.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of mark.
Example(s):
onyx:0> sprintsdict begin
onyx:0> mark
onyx:1> dup 0 marktype print `\n' print flush
-mark-
onyx:1> dup 1 marktype print `\n' print flush
-mark-
onyx:1>
mutex depth mutextype string:
Input(s):
mutex:
A mutex object.
depth:
Recursion depth.
Output(s):
string:
Syntactical string representation of mutex.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of mutex.
Example(s):
onyx:0> sprintsdict begin
onyx:0> mutex
onyx:1> dup 0 mutextype print `\n' print flush
-mutex-
onyx:1> dup 1 mutextype print `\n' print flush
-mutex-
onyx:1>
name depth nametype string:
Input(s):
name:
A name object.
depth:
Recursion depth.
Output(s):
string:
Syntactical string representation of name.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of name.
Example(s):
onyx:0> sprintsdict begin
onyx:0> /foo
onyx:1> dup 0 nametype print `\n' print flush
/foo
onyx:1> dup 1 nametype print `\n' print flush
/foo
onyx:1>
null depth nulltype string:
Input(s):
null:
A null object.
depth:
Recursion depth.
Output(s):
string:
Syntactical string representation of null.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of null.
Example(s):
onyx:0> sprintsdict begin
onyx:0> null
onyx:1> dup 0 nulltype print `\n' print flush
-null-
onyx:1> dup 1 nulltype print `\n' print flush
-null-
onyx:1>
operator depth operatortype string:
Input(s):
operator:
An operator object.
depth:
Recursion depth.
Output(s):
string:
Syntactical string representation of operator.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of operator.
Example(s):
The following example shows an operator printed out with two leading and trailing dashes. If the interpreter cannot determine the name associated with an operator, as will be the case for custom operators, the operator will be printed as -operator-.
onyx:0> sprintsdict begin
onyx:0> //realtime
onyx:1> dup 0 operatortype print `\n' print flush
--realtime--
onyx:1> 1 operatortype print `\n' print flush
--realtime--
onyx:0>
pmark depth pmarktype string:
Input(s):
pmark:
A pmark object.
depth:
Recursion depth.
Output(s):
string:
Syntactical string representation of pmark.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of pmark.
Example(s):
onyx:0> sprintsdict begin
onyx:0> { //x
Error /undefined
ostack: (-pmark- /x)
dstack: (-dict- -dict- -dict- -dict- -dict-)
estack/istack trace (0..1):
0:      -file-
1:      --start--
onyx:3> pop pop resume
onyx:1> dup 0 pmarktype print `\n' print flush
-pmark-
onyx:1> dup 1 pmarktype print `\n' print flush
-pmark-
onyx:1>
stack depth stacktype string:
Input(s):
stack:
A stack object.
depth:
Recursion depth.
Output(s):
string:
Syntactical string representation of stack.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of stack.
Example(s):
onyx:0> sprintsdict begin
onyx:0> (1 (2 3) 4)
onyx:1> dup 0 stacktype print `\n' print flush
-stack-
onyx:1> dup 1 stacktype print `\n' print flush
(1 -stack- 4)
onyx:1> dup 2 stacktype print `\n' print flush
(1 (2 3) 4)
onyx:1>
string depth stringtype string:
Input(s):
string:
A string object.
depth:
Recursion depth.
Output(s):
string:
Syntactical string representation of string.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of string.
Example(s):
onyx:0> sprintsdict begin
onyx:0> `abcd'
onyx:1> dup 0 stringtype print `\n' print flush
`abcd'
onyx:1> dup 1 stringtype print `\n' print flush
`abcd'
onyx:1>
thread depth threadtype string:
Input(s):
thread:
A thread object.
depth:
Recursion depth.
Output(s):
string:
Syntactical string representation of thread.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of thread.
Example(s):
onyx:0> sprintsdict begin
onyx:0> thread
onyx:1> dup 0 threadtype print `\n' print flush
-thread-
onyx:1> dup 1 threadtype print `\n' print flush
-thread-
onyx:1>


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 1.9: systemdict summary by functional group
Input(s) Op/Proc/Var Output(s) Description
Operand stack operators
- mark mark Create a mark.
- count count Get the number of objects on ostack.
mark ... counttomark mark ... count Get the depth of the topmost mark on ostack.
object dup object object Duplicate an object.
objects count ndup objects objects Duplicate objects.
object ...index index object ... object Duplicate object on ostack at a given index.
a b exch b a Exchange the top two objects on ostack.
region count amount roll rolled Roll the top count objects up by amount.
any pop - Remove the top object from ostack.
objects count npop - Remove objects from ostack.
objects clear - Pop all objects off ostack.
mark ... cleartomark - Remove objects from ostack through topmost mark.
- ostack stack Get a current ostack snapshot.
Execution, control, and execution stack operators
object eval - Evaluate object.
boolean object if - 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.
proc loop - Iterate 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.
- exit - Terminate innermost looping context.
file/string token false Scan for a token.
file/string token file/substring object true Scan for a token.
object start - Evaluate object.
- quit - Unwind to innermost start context.
object stopped boolean Evaluate object.
- stop - Unwind to innermost stopped or start context.
name throw object Throw an error.
- estack stack Get a current estack snapshot.
- countestack count Get current estack depth.
- istack stack Get a current istack snapshot.
status die - Exit program.
- fork pid Fork a new process.
args exec - Overlay a new program and execute it.
pid waitpid status Wait for a program to terminate.
args system status Execute a program.
- 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.
- realtime nsecs Get the number of nanoseconds since the epoch.
nanoseconds nsleep - Nanosleep.
Stack operators
- ( fino Begin a stack declaration.
fino objects ) stack Create a stack.
- stack stack Create a stack.
stack object spush - Push an object onto a 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 index sindex - Duplicate object in a stack at a given index.
stack sexch - Exchange top objects on stack.
stack count amount sroll - Roll objects on stack.
stack spop object Pop an object off stack.
stack sclear - Remove all objects on stack.
stack scleartomark - Remove objects from stack down through topmost mark.
(a) (b) catenate (a b) Catenate two stacks.
srcstack dststack copy dststack Copy stack contents.
Integer and math operators
a b add r Add a and b.
a b sub r Subtract b from a.
a b mul r Multiply a and b.
a b div r Divide a by b.
a b mod r Mod a by b.
a b exp r Raise a to the power of b.
a abs r Get the absolute value of a.
a neg r Get the negative of a.
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' catenate `ab' Catenate two strings.
srcstring dststring copy dstsubstring Copy string.
object depth sprints string Create syntactical string from object.
object flags outputs string Create formatted string from object.
Name operators
name length count Get name length.
Array operators
- argv args Get program arguments.
- [ 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 object Get array element.
array index object put - Set array element.
array index length getinterval subarray Get an array interval.
array index subarray putinterval - Copy subarray into array.
[a] [b] catenate [a b] Catenate two arrays.
srcarray dstarray copy dstsubarray Copy array.
Dictionary and dictionary stack operators
- gcdict dict Get gcdict.
- globaldict dict Get globaldict.
- sprintsdict dict Get sprintsdict.
- outputsdict dict Get outputsdict.
- envdict dict Get envdict.
key val setenv - Set environment variable.
key unsetenv - Unset environment variable.
- < 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 Get topmost dstack dictionary that defines key.
key where dict true 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.
- countdstack count Get number of stacks on dstack.
- cleardstack - Pop all dstack elements pushed by begin .
File and filesystem operators
filename flags open file Open a file.
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 bytesavailable count Get number of buffered readable bytes.
file integer/string write - Write to file.
string print - Print string to stdout.
object depth sprint - Syntactically print object to stdout.
object 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 mode mkdir - Create a directory.
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.
path proc dirforeach - Iterate on directory entries.
- pwd path Get present working directory.
path cd - Change present working directory.
- stdin file Get stdin.
- stdout file Get stdout.
- stderr file Get stderr.
Logical and bitwise operators
a b lt boolean a less than b? (integer, string)
a b le boolean a less than or equal to b? (integer, 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, string)
a b gt boolean a greater than b? (integer, 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
object type name Get object type.
object echeck boolean Evaluatable?
object xcheck boolean Executable?
object cve object Set evaluatable attribute.
object cvx object Set executable attribute.
object cvlit object Set literal attribute.
string cvn name Convert string to name.
object cvs string Convert object to string.
hook hooktag tag Get hook tag.
integer radix cvrs string Convert integer to radix 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.
object lcheck boolean Implicitly locked?
Miscellaneous operators
- #! mark Begin interpreter magic.
mark names !# - End interpreter magic.
- 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.

mark names !# -:
Input(s):
mark:
A mark object.
names:
Zero or more name objects.
Output(s):
None.
Errors(s):
unmatchedmark.
Description:
Remove mark and name objects constructed as a side effect of interpreter magic. This operator is an alias of cleartomark.
Example(s):
onyx:0> #!/usr/local/bin/onyx pstack
/onyx
/bin
/local
/usr
-mark-
onyx:5> !#
onyx:0>
- #! mark:
Input(s):
None.
Output(s):
mark:
A mark object.
Errors(s):
None.
Description:
Create a mark object in preparation for an interpreter path. This operator is an alias of mark.
Example(s):
onyx:0> #! pstack
-mark-
onyx:1>
- ( fino:
Input(s):
None.
Output(s):
fino:
A fino object.
Errors(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.
Errors(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.
Errors(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.
Errors(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.
Errors(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.
Errors(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.
Output(s):
r:
Absolute value of a.
Errors(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>
a b add r:
Input(s):
a:
An integer.
b:
An integer.
Output(s):
r:
The sum of a and b.
Errors(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>
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.
Errors(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.
Errors(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.
Errors(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>
dict begin -:
Input(s):
dict:
A dictionary.
Output(s):
None.
Errors(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.
Errors(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 evaluatable operator.
  • The value is an evaluatable array.
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>
condition broadcast -:
Input(s):
condition:
A condition object.
Output(s):
None.
Errors(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.
Errors(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] catenate [a b]:
(a) (b) catenate (a b):
`a' `b' catenate `ab':
Input(s):
a:
An array, stack, or string.
b:
An array, stack, or string.
Output(s):
ab:
The catenation of a and b.
Errors(s):
stackunderflow.
typecheck.
Description:
Catenate two arrays, strings, or stacks.
Example(s):
onyx:0> [`a'] [`b'] catenate
onyx:1> 1 sprint
[`a' `b']
onyx:0> (`a') (`b') catenate
onyx:1> 1 sprint
(`a' `b')
onyx:0> `a' `b' catenate
onyx:1> 1 sprint
`ab'
onyx:0>
path cd -:
Input(s):
path:
A string that represents a filesystem path.
Output(s):
None.
Errors(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>
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.
Errors(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.
Errors(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>
objects clear -:
Input(s):
objects:
All objects on ostack.
Output(s):
None.
Errors(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>
- cleardstack -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
Pop all dictionaries on dstack that were pushed by begin .
Example(s):
onyx:0> dict begin
onyx:0> dstack 1 sprint
(-dict- -dict- -dict- -dict- -dict-)
onyx:0> cleardstack
onyx:0> dstack 1 sprint
(-dict- -dict- -dict- -dict-)
onyx:0> cleardstack
onyx:0> dstack 1 sprint
(-dict- -dict- -dict- -dict-)
onyx:0>
mark ... cleartomark -:
Input(s):
mark:
A mark object.
...:
Zero or more non-mark objects.
Output(s):
None.
Errors(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.
Errors(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.
Errors(s):
None.
Description:
Create a condition object.
Example(s):
onyx:0> condition 1 sprint
-condition-
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.
Errors(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>
- count count:
Input(s):
None.
Output(s):
count:
The number of objects on ostack.
Errors(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.
Errors(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).
Errors(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):
mark:
A mark object.
...:
Zero or more non-mark objects.
Output(s):
mark:
The same mark that was passed in.
...:
The same non-mark objects that were passed in.
count:
The depth of mark on ostack.
Errors(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>
- currentdict dict:
Input(s):
None.
Output(s):
dict:
Topmost stack on dstack.
Errors(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.
Errors(s):
None.
Description:
Get the current implicit locking mode. See Section 1.6.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>
object cve object:
Input(s):
object:
An object.
Output(s):
object:
The same object that was passed in, but with the evaluatable attribute set.
Errors(s):
stackunderflow.
Description:
Set the evaluatable attribute for object.
Example(s):
onyx:0> [1 2 3] cve 1 sprint
_{1 2 3}_
onyx:0>
object cvlit object:
Input(s):
object:
An object.
Output(s):
object:
The same object that was passed in, but with the literal attribute set.
Errors(s):
stackunderflow.
Description:
Set the literal attribute for object.
Example(s):
onyx:0> {1 2 3} cvlit 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.
Errors(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.
Errors(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>
object cvs string:
Input(s):
object:
An object.
Output(s):
string:
A string representation of object. The string depends on the type of object:
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-'.
string:
A printable representation of object. The result can be evaluated to produce the original string.
Other types:
`-nostringval-'.
Errors(s):
stackunderflow.
Description:
Convert object 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> `foo\nbar\\biz\`baz' cvs 1 sprint
`\`foo\\nbar\\\\biz\\\`baz\''
onyx:0> mutex cvs 1 sprint
`--nostringval--'
onyx:0>
object cvx object:
Input(s):
object:
An object.
Output(s):
object:
The same object that was passed in, but with the executable attribute set.
Errors(s):
stackunderflow.
Description:
Set the executable attribute for object.
Example(s):
onyx:0> [1 2 3] cvx 1 sprint
{1 2 3}
onyx:0>
key val def -:
Input(s):
key:
An object.
val:
A value associated with key.
Output(s):
None.
Errors(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.
Errors(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.
Errors(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.
Errors(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.
Errors(s):
invalidaccess.
ioerror.
stackunderflow.
typecheck.
Description:
For each entry in the directory represented by path, push a string that represents the entry onto ostack and execute proc. This operator supports the exit operator.
Example(s):
onyx:0> pwd {1 sprint} dirforeach
`.'
`..'
`CVS'
`.cvsignore'
`Cookfile'
`Cookfile.inc'
`latex'
`ps'
`pdf'
`html'
onyx:0> pwd {`Cookfile.inc' search
     {pop `Yes: ' print 1 sprint pop exit}
     {`Not: ' print 1 sprint} ifelse
} dirforeach
Not: `.'
Not: `..'
Not: `CVS'
Not: `.cvsignore'
Not: `Cookfile'
Yes: `Cookfile.inc'
onyx:0>
a b div r:
Input(s):
a:
An integer.
b:
A non-zero integer.
Output(s):
r:
The quotient of a divided by b.
Errors(s):
stackunderflow.
typecheck.
undefinedresult.
Description:
Return the quotient of a divided by b.
Example(s):
onyx:0> 4 2 div 1 sprint
2
onyx:0> 5 2 div 1 sprint
2
onyx:0> 5 0 div
Error /undefinedresult
ostack: (5 0)
dstack: (-dict- -dict- -dict- -dict-)
estack/istack trace (0..2):
0:      --div--
1:      -file-
2:      --start--
onyx:3>
- dstack stack:
Input(s):
None.
Output(s):
stack:
A snapshot of dstack.
Errors(s):
None.
Description:
Get a snapshot of dstack.
Example(s):
onyx:0> dstack 1 sprint
(-dict- -dict- -dict- -dict-)
onyx:0>
object dup object object:
Input(s):
object:
An object.
Output(s):
object:
The same object that was passed in.
Errors(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>
object echeck boolean:
Input(s):
object:
An object.
Output(s):
boolean:
True if object has the evaluatable attribute, false otherwise.
Errors(s):
stackunderflow.
Description:
Check object for evaluatable 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.
Errors(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.
Errors(s):
dstackunderflow.
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-)
estack/istack trace (0..2):
0:      foo
1:      -file-
2:      --start--
onyx:1>
- envdict dict:
Input(s):
None.
Output(s):
dict:
A dictionary.
Errors(s):
None.
Description:
Get envdict. See Section 1.8.2 for details on envdict.
Example(s):
onyx:0> envdict 0 sprint
-dict-
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.
Errors(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, hook, 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:
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>
- estack stack:
Input(s):
None.
Output(s):
stack:
A current snapshot (copy) of the execution stack.
Errors(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.
Errors(s):
None.
Description:
Get the process's effective user ID.
Example(s):
onyx:0> euid 1 sprint
1001
onyx:0>
object eval -:
Input(s):
object:
An object.
Output(s):
None.
Errors(s):
stackunderflow.
Description:
Evaluate object. See Section 1.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.
Errors(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).
Errors(s):
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.
Errors(s):
None.
Description:
Exit the innermost enclosing looping context immediately. This operator can be called within the looping context of for , repeat , loop , foreach , and dirforeach .
Example(s):
onyx:0> {`hi' 1 sprint exit `bye' 1 sprint} loop
`hi'
onyx:0>
a b exp r:
Input(s):
a:
An integer.
b:
A non-negative. integer.
Output(s):
r:
a to the b power.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Return a to the b power.
Example(s):
onyx:0> 5 0 exp 1 sprint
1
onyx:0> 5 1 exp 1 sprint
5
onyx:0> 5 2 exp 1 sprint
25
onyx:0> -5 3 exp 1 sprint
-125
onyx:0> 5 -3 exp 1 sprint
Error /rangecheck
ostack: (5 -3)
dstack: (-dict- -dict- -dict- -dict-)
estack/istack trace (0..2):
0:      --exp--
1:      -file-
2:      --start--
onyx:3>
- false false:
Input(s):
None.
Output(s):
false:
The boolean value false.
Errors(s):
None.
Description:
Return false.
Example(s):
onyx:0> false 1 sprint
false
onyx:0>
- flush -:
Input(s):
None.
Output(s):
None.
Errors(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.
Errors(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.
Errors(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 exit operator.
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.
Errors(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 exit operator.
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>
- fork pid:
Input(s):
None.
Output(s):
pid:
Process identifier for the new process, or 0 if the child process.
Errors(s):
limitcheck.
Description:
Fork a new process. Care must be taken when using the fork operator due to the fact that onyx consumes programs on the fly. The child process cannot reliably scan onyx code from the same source as the parent, so the child process should be forked into an environment where it is executing an object that has already been constructed by the interpreter, which in turn avoids unwinding the onyx execution stack.
Example(s):
onyx:0> {fork dup 0 eq
        {pop `Child\n' print flush}
        {`Parent\n' print flush waitpid}
        ifelse} eval
Parent
Child
onyx:0>
- gcdict dict:
Input(s):
None.
Output(s):
dict:
A dictionary.
Errors(s):
None.
Description:
Get gcdict. See Section 1.8.2 for details on envdict.
Example(s):
onyx:0> gcdict 0 sprint
-dict-
onyx:0>
a b ge boolean:
Input(s):
a:
An integer or string.
b:
The same type as a.
Output(s):
boolean:
True if a is greater than or equal to b, false otherwise.
Errors(s):
stackunderflow.
typecheck.
Description:
Compare two integers 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> `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 object:
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):
object:
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.
Errors(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.
Errors(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>
- gid gid:
Input(s):
None.
Output(s):
gid:
Process's group ID.
Errors(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.
Errors(s):
None.
Description:
Get globaldict. See Section 1.8.2 for details on envdict.
Example(s):
onyx:0> globaldict 1 sprint
<>
onyx:0>
a b gt boolean:
Input(s):
a:
An integer or string.
b:
The same type as a.
Output(s):
boolean:
True if a is greater than b, false otherwise.
Errors(s):
stackunderflow.
typecheck.
Description:
Compare two integers or strings.
Example(s):
onyx:0> 1 1 gt 1 sprint
false
onyx:0> 2 1 gt 1 sprint
true
onyx:0> `a' `a' gt 1 sprint
false
onyx:0> `b' `a' gt 1 sprint
true
onyx:0>
hook hooktag tag:
Input(s):
hook:
A hook object.
Output(s):
tag:
The tag associated with hook.
Errors(s):
stackunderflow.
typecheck.
Description:
Get the tag associated with hook.
Example(s):

boolean object if -:
Input(s):
boolean:
A boolean.
object:
An object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Evaluate object 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.
Errors(s):
stackunderflow.
typecheck.
Description:
Evaluate a if boolean is true, evaluate b otherwise. See Section 1.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>
object ...index index object ...object:
Input(s):
object:
An object.
...:
index objects.
index:
Depth (count starts at 0, not counting index) of the object to duplicate on ostack.
Output(s):
object:
The same object that was passed in.
...:
The same index objects that were passed in.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Create a duplicate of the object on on ostack at depth index.
Example(s):
onyx:0> 3 2 1 0 2 index pstack
2
0
1
2
3
onyx:5>
- istack stack:
Input(s):
None.
Output(s):
stack:
A current snapshot (copy) of the index stack.
Errors(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.
Errors(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>
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.
Errors(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>
object lcheck boolean:
Input(s):
object:
An array, dict, file, or string.
Output(s):
boolean:
True if object is implicitly locked, false otherwise.
Errors(s):
stackunderflow.
typecheck.
Description:
Check if object is implicitly locked.
Example(s):
onyx:0> false setlocking
onyx:0> [1 2 3] lcheck 1 sprint
false
onyx:0> true setlocking
onyx:0> [1 2 3] lcheck 1 sprint
true
onyx:0>
a b le boolean:
Input(s):
a:
An integer or string.
b:
The same type as a.
Output(s):
boolean:
True if a is less than or equal to b, false otherwise.
Errors(s):
stackunderflow.
typecheck.
Description:
Compare two integers 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> `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.
Errors(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.
Errors(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>
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.
Errors(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>
mutex lock -:
Input(s):
mutex:
A mutex object.
Output(s):
None.
Errors(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>
proc loop -:
Input(s):
proc:
An object to evaluate.
Output(s):
None.
Errors(s):
stackunderflow.
Description:
Iteratively evaluate proc indefinitely. This operator supports the exit operator.
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:
An integer or string.
b:
The same type as a.
Output(s):
boolean:
True if a is less than b, false otherwise.
Errors(s):
stackunderflow.
typecheck.
Description:
Compare two integers or strings.
Example(s):
onyx:0> 1 2 lt 1 sprint
true
onyx:0> 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.
Errors(s):
None.
Description:
Push a mark onto ostack.
Example(s):
onyx:0> mark pstack
-mark-
onyx:1>
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.
Errors(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>
a b mod r:
Input(s):
a:
An integer.
b:
A non-zero integer.
Output(s):
r:
The modulus of a and b.
Errors(s):
stackunderflow.
typecheck.
undefinedresult.
Description:
Return the modulus of a and b.
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-)
estack/istack trace (0..2):
0:      --mod--
1:      -file-
2:      --start--
onyx:3>
mutex proc monitor -:
Input(s):
mutex:
A mutex.
proc:
Any object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Execute proc while holding mutex.
Example(s):
onyx:0> mutex {`hello\n' print} monitor flush
hello
onyx:0>
a b mul r:
Input(s):
a:
An integer.
b:
An integer.
Output(s):
r:
The product of a and b.
Errors(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>
- mutex mutex:
Input(s):
None.
Output(s):
mutex:
A mutex object.
Errors(s):
None.
Description:
Create a mutex.
Example(s):
onyx:0> mutex 1 sprint
-mutex-
onyx:0>
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.
Errors(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.
Errors(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, hook, 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:
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>
a neg r:
Input(s):
a:
An integer.
Output(s):
r:
The negative of a.
Errors(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>
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.
Errors(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.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Remove the top count objects off 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.
Errors(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.
Errors(s):
None.
Description:
Create a null object.
Example(s):
onyx:0> null pstack
null
onyx:1>
filename flags 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.
Output(s):
file:
A file object.
Errors(s):
invalidfileaccess.
ioerror.
limitcheck.
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.
Errors(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>
- ostack stack:
Input(s):
None.
Output(s):
stack:
A current snapshot (copy) of ostack.
Errors(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>
object depth output -:
Input(s):
object:
An object to print syntactically.
depth:
Maximum recursion depth.
Output(s):
None.
Errors(s):
ioerror.
stackunderflow.
typecheck.
Description:
Syntactically print object.
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 catenate </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>
object flags outputs string:
Input(s):
object:
An object to print syntactically.
depth:
Formatting flags. See Section 1.8.6 for details on the supported flags.
Output(s):
string:
A formatted string representation of object.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of object.
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 catenate </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.
Errors(s):
None.
Description:
Get outputsdict. See Section 1.8.6 for details on outputsdict.
Example(s):
onyx:0> outputsdict 0 sprint
-dict-
onyx:0>
- pid pid:
Input(s):
None.
Output(s):
pid:
Process identifier.
Errors(s):
None.
Description:
Get the process ID of the running process.
Example(s):
onyx:0> pid 1 sprint
80624
onyx:0>
any pop -:
Input(s):
any:
Any object.
Output(s):
None.
Errors(s):
stackunderflow.
Description:
Remove the top object off ostack and discard it.
Example(s):
onyx:0> 1 2
onyx:2> pstack
2
1
onyx:2> pop
onyx:1> pstack
1
onyx:1>
- ppid pid:
Input(s):
None.
Output(s):
pid:
Process identifier.
Errors(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.
Errors(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'.
Errors(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.
Errors(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 object 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 object or integer, respectively.
key:
An object to use as a key in dict.
object:
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.
Errors(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.
Errors(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.
Errors(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.
Errors(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.
Errors(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.
Errors(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.
Errors(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>
- realtime nsecs:
Input(s):
None.
Output(s):
nsecs:
Number of nanoseconds since the epoch (midnight on 1 January 1970).
Errors(s):
None.
Description:
Get the number of nanoseconds since the epoch.
Example(s):
onyx:0> realtime 1 sprint
993539837806479000
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.
Errors(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.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Evaluate proc count times. This operator supports the exit operator.
Example(s):
onyx:0> 3 {`hi' 1 sprint} repeat
`hi'
`hi'
`hi'
onyx:0>
path rmdir -:
Input(s):
path:
A string object that represents a directory path.
Output(s):
None.
Errors(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.
Errors(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>
stack sclear -:
Input(s):
stack:
A stack object.
Output(s):
None.
Errors(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.
Errors(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.
Errors(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.
Errors(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 sdup -:
Input(s):
stack:
A stack object.
Output(s):
None.
Errors(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.
Errors(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.
Errors(s):
None.
Description:
Get a thread object for the running thread.
Example(s):
onyx:0> self 1 sprint
-thread-
onyx:0>
gid setegid boolean:
Input(s):
gid:
A group ID.
Output(s):
boolean:
If false, success, otherwise failure.
Errors(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.
Errors(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. An 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.
Errors(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.
Errors(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>
boolean setlocking -:
Input(s):
boolean:
A boolean to set the implicit locking mode to.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Set the current implicit locking mode. See Section 1.6.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>
uid setuid boolean:
Input(s):
uid:
A user ID.
Output(s):
boolean:
If false, success, otherwise failure.
Errors(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.
Errors(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.
Errors(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>
condition signal -:
Input(s):
condition:
A condition object.
Output(s):
None.
Errors(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>
stack index sindex -:
Input(s):
stack:
A stack object.
index:
Depth (count starts at 0) of the object to duplicate in stack.
Output(s):
None.
Errors(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 sindex
onyx:1> 1 sprint
(3 2 1 0 2)
onyx:0>
stack spop object:
Input(s):
stack:
A stack object.
Output(s):
object:
The object that was popped off of stack.
Errors(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>
object depth sprint -:
Input(s):
object:
An object to print syntactically.
depth:
Maximum recursion depth.
Output(s):
None.
Errors(s):
ioerror.
stackunderflow.
typecheck.
Description:
Syntactically print object.
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>
object depth sprints string:
Input(s):
object:
An object to print syntactically.
depth:
Maximum recursion depth.
Output(s):
string:
A syntactical string representation of object.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of object.
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.
Errors(s):
None.
Description:
Get sprintsdict. See Section 1.8.7 for details on sprintsdict.
Example(s):
onyx:0> sprintsdict 0 sprint
-dict-
onyx:0>
stack object spush -:
Input(s):
stack:
A stack object.
object:
An object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Push object onto stack.
Example(s):
onyx:0> () dup 1 spush
onyx:1> pstack
(1)
onyx:1>
seed srand -:
Input(s):
seed:
A non-negative integer.
Output(s):
None.
Errors(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.
Errors(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 stack:
Input(s):
None.
Output(s):
stack:
An empty stack object.
Errors(s):
None.
Description:
Create a new stack object and push it onto ostack.
Example(s):
onyx:0> stack
onyx:1> pstack
()
object start -:
Input(s):
object:
An object.
Output(s):
None.
Errors(s):
stackunderflow.
Description:
Evaluate object. 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.
Errors(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 stderr.
Errors(s):
None.
Description:
Get stdout.
Example(s):
onyx:0> stderr pstack
-file-
onyx:1>
- stdin file:
Input(s):
None.
Output(s):
file:
A file object corresponding to stdin.
Errors(s):
None.
Description:
Get stdin.
Example(s):
onyx:0> stdin pstack
-file-
onyx:1>
- stdout file:
Input(s):
None.
Output(s):
file:
A file object corresponding to stdout.
Errors(s):
None.
Description:
Get stdout.
Example(s):
onyx:0> stdout pstack
-file-
onyx:1>
- stop -:
Input(s):
None.
Output(s):
None.
Errors(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>
object stopped boolean:
Input(s):
object:
An object to evaluate.
Output(s):
boolean:
True if stop operator was executed, false otherwise.
Errors(s):
invalidexit.
stackunderflow.
Description:
Evaluate object. This operator provides a context that terminates execution stack unwinding due to the stop . It will also terminate execution stack unwinding due to the exit operator, but will throw an invalidexit error, 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.
Errors(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>
a b sub r:
Input(s):
a:
An integer.
b:
An integer.
Output(s):
r:
The value of b subtracted from a.
Errors(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>
filename linkname symlink -:
Input(s):
filename:
A string that represents a filename.
linkname:
A string that represents a filename.
Output(s):
None.
Errors(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>
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.
Errors(s):
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>
file tell offset:
Input(s):
fil:
A file object.
Output(s):
offset:
Offset of the file position pointer for file.
Errors(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.
Errors(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>
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.
Errors(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>
name throw object:
Input(s):
name:
The name of an error, which can be any of the following:
dstackunderflow .
estackoverflow .
invalidaccess .
invalidexit .
invalidfileaccess .
ioerror .
limitcheck .
rangecheck .
stackunderflow .
syntaxerror .
typecheck .
undefined .
undefinedfilename .
undefinedresult .
unmatchedmark .
unmatchedfino .
unregistered .
Output(s):
object:
The object that was being executed when the error was thrown.
Errors(s):
stackunderflow.
typecheck.
undefined.
Description:
Throw an error. This operator goes through 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. Evaluate the error handler in the errordict dictionary that corresponds to name.
  6. Evaluate the errordict dictionary's stop .
Example(s):
onyx:0> /unregistered throw
Error /unregistered
ostack: ()
dstack: (-dict- -dict- -dict- -dict-)
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.
Errors(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 index dup lock 1000000000 timedwait 1 sprint unlock
true
onyx:0>
file/string token false:
file/string token file/substring object 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.
object:
An object that was constructed by scanning a token.
false/true:
If true, a token was successfully scanned, false otherwise.
Errors(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>
file length truncate -:
Input(s):
file:
A file object.
length:
New length for file.
Output(s):
None.
Errors(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.
Errors(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.
Errors(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>
object type name:
Input(s):
object:
An object.
Output(s):
name:
An executable name that corresponds to the type of object:
array:
arraytype.
boolean:
booleantype.
condition:
conditiontype.
dict:
dicttype.
file:
filetype.
fino:
finotype.
hook:
hooktype.
integer:
integertype.
mark:
marktype.
mutex:
mutextype.
name:
nametype.
null:
nulltype.
operator:
operatortype.
pmark:
pmarktype.
stack:
stacktype.
string:
stringtype.
thread:
threadtype.
Errors(s):
stackunderflow.
Description:
Get a name that represent the type of object.
Example(s):
onyx:0> true type 1 sprint
booleantype
onyx:0>
- uid uid:
Input(s):
None.
Output(s):
uid:
Process's user ID.
Errors(s):
None.
Description:
Get the process's user ID.
Example(s):
onyx:0> uid 1 sprint
1001
onyx:0>
dict key undef -:
Input(s):
dict:
A dictionary.
val:
A key in dict to undefine.
Output(s):
None
Errors(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>
filename unlink -:
Input(s):
filename:
A string that represents a filename.
Output(s):
None.
Errors(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-)
estack/istack trace (0..2):
0:      --open--
1:      -file-
2:      --start--
onyx:3>
mutex unlock -:
Input(s):
mutex:
A mutex object.
Output(s):
None.
Errors(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.
Errors(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>
- version string:
Input(s):
None.
Output(s):
string:
A string that contains the version name.
Errors(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.
Errors(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.
Errors(s):
stackunderflow.
typecheck.
Description:
Wait for the process with process ID pid to exit.
Example(s):
onyx:0> {fork dup 0 eq
        {pop `Child\n' print flush}
        {`Parent\n' print flush waitpid}
        ifelse} eval
Parent
Child
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.
Errors(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 --stop-->
onyx:0>
file integer/string write -:
Input(s):
file:
A file object.
integer:
An integer that represents an ascii character value.
string:
A string object.
Output(s):
None.
Errors(s):
ioerror.
stackunderflow.
typecheck.
Description:
Write integer or string to file.
Example(s):
onyx:0> `/tmp/foo' `w+' open
onyx:1> dup `Hello\n' write
onyx:1> dup 0 seek
onyx:1> dup readline 1 sprint 1 sprint
false
`Hello'
onyx:1>
object xcheck boolean:
Input(s):
object:
An object.
Output(s):
boolean:
True if object has the executable or evaluatable attribute, false otherwise.
Errors(s):
stackunderflow.
Description:
Check object for executable or evaluatable attribute.
Example(s):
onyx:0> {1 2 3} xcheck 1 sprint
true
onyx:0> [1 2 3] xcheck 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.
Errors(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.
Errors(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>


threaddict

Each thread has its own threaddict, which is not shared with any other threads. threaddict is meant to be used for thread-specific definitions that would otherwise go in systemdict.

Table 1.10: threaddict summary
Input(s) Op/Proc/Var Output(s) Description
- threaddict dict Get threaddict.
- userdict dict Get userdict.
- currenterror dict Get currenterror.
- errordict dict Get errordict.

- currenterror dict:
Input(s):
None.
Output(s):
dict:
The currenterror dictionary. See Section 1.8.1 for details on currenterror.
Errors(s):
None.
Description:
Get currenterror.
Example(s):
onyx:0> currenterror 0 sprint
-dict-
onyx:0>
- errordict dict:
Input(s):
None.
Output(s):
dict:
The errordict dictionary. See Section 1.8.3 for details on errordict.
Errors(s):
None.
Description:
Get errordict.
Example(s):
onyx:0> errordict 0 sprint
-dict-
onyx:0>
- threaddict dict:
Input(s):
None.
Output(s):
dict:
The threaddict dictionary.
Errors(s):
None.
Description:
Get threaddict.
Example(s):
onyx:0> threaddict 0 sprint
-dict-
onyx:0>
- userdict dict:
Input(s):
None.
Output(s):
dict:
The userdict dictionary. See Section 1.8.10 for details on userdict.
Errors(s):
None.
Description:
Get userdict.
Example(s):
onyx:0> userdict 1 sprint
<>
onyx:0>


userdict

Each thread has its own userdict, which is not shared with any other threads. userdict is meant to be used for general storage of definitions that do not need to be shared among threads. userdict starts out empty when a thread is created.


next up previous contents index
Next: The onyx program Up: Contents Previous: Contents   Contents   Index
Jason Evans 2001-08-21