Ode Language Documentation

This documentation is borrowed from the original Joy language documentation, with modifications to clarify how certain operators function in the Ode environment.

Literals

Boolean/Logical Literals

The logical type, or the type of truth values. It has just two literals: true and false.

false => false

Character Literals

The type of characters. Literals are written with a single quote. Examples: 'A '7 '; and so on. Unix style escapes are allowed.

Integer Literals

The type of negative, zero or positive integers. Literals are written in decimal notation. Examples: -123 0 42.

Set Literals

The type of sets of small non-negative integers. The maximum is platform dependent, typically the range is 0..31. Literals are written inside curly braces.

Examples:

• {}
• {0}
• {1 3 5}
• {19 18 17}

String Literals

The type of strings of characters. Literals are written inside double quotes. Examples: "" "A" "hello world" "123". Unix style escapes are accepted.

List Literals

The type of lists of values of any type (including lists), or the type of quoted programs which may contain operators or combinators. Literals of this type are written inside square brackets.

Examples:

• []
• [3 512 -7]
• [john mary]
• ['A 'C ['B]]
• [dup *]

Float Literals

The type of floating-point numbers. Literals of this type are written with embedded decimal points (like 1.2) and optional exponent specifiers (like 1.5E2).

Definitions and Symbols

==

Defines a definition.

double == dup +;

name : sym -> "sym"

For operators and combinators, the string "sym" is the name of item sym, for literals sym the result string is its type.

intern : "sym" -> sym

Pushes the item whose name is "sym".

Math

+ : M I -> N

Numeric N is the result of adding integer I to numeric M. Also supports float.

succ : M -> N

Numeric N is the successor of numeric M.

div : I J -> K L

Integers K and L are the quotient and remainder of dividing I by J.

rem : I J -> K

Integer K is the remainder of dividing I by J. Also supports float.

- : M I -> N

Numeric N is the result of subtracting integer I from numeric M. Also supports float.

* : I J -> K

Integer K is the product of integers I and J. Also supports float.

/ : I J -> K

Integer K is the (rounded) ratio of integers I and J. Also supports float.

Boolean Operations

choice : B T F -> X

If B is true, then X = T else X = F.

or : X Y -> Z

Z is the logical disjunction for truth values.

xor : X Y -> Z

Z is the logical exclusive disjunction for truth values.

and : X Y -> Z

Z is the logical conjunction for truth values.

not : X -> Y

Y is the logical negation for truth values.

>= : X Y -> B

Either both X and Y are numeric or both are strings or symbols. Tests whether X greater than or equal to Y. Also supports float.

> : X Y -> B

Either both X and Y are numeric or both are strings or symbols. Tests whether X greater than Y. Also supports float.

!= : X Y -> B

Either both X and Y are numeric or both are strings or symbols. Tests whether X not equal to Y. Also supports float.

= : X Y -> B

Either both X and Y are numeric or both are strings or symbols. Tests whether X equal to Y. Also supports float.

< : X Y -> B

Either both X and Y are numeric or both are strings or symbols. Tests whether X less than Y. Also supports float.

<= : X Y -> B

Either both X and Y are numeric or both are strings or symbols. Tests whether X less than or equal to Y. Also supports float.

null : X -> B

Tests for empty aggregate X or zero numeric.

small : X -> B

Tests whether aggregate X has 0 or 1 members, or numeric 0 or 1.

integer : X -> B

Tests whether X is an integer.

char : X -> B

Tests whether X is a character.

logical : X -> B

Tests whether X is a logical.

set : X -> B

Tests whether X is a set.

string : X -> B

Tests whether X is a string.

list : X -> B

Tests whether X is a list.

float : R -> B

Tests whether R is a float.

Aggregate Operations

concat : S T -> U

Sequence U is the concatenation of sequences S and T.

size : A -> I

Integer I is the number of elements of aggregate A.

cons : X A -> B

Aggregate B is A with a new member X (first member for sequences).

swons : A X -> B

Aggregate B is A with a new member X (first member for sequences). This is the same as cons, but with the arguments reversed.

uncons : A -> F R

F and R are the first and the rest of non-empty aggregate A.

i : [P] -> ...

Executes P. So, [P] i == P.

rest : A -> R

R is the non-empty aggregate A with its first member removed.

first : A -> F

F is the first member of the non-empty aggregate A.

Functional Operations

map : A [P] -> B

Executes P on each member of aggregate A, collects results in same type aggregate B.

fold : A V0 [P] -> V

Starting with value V0, sequentially pushes members of aggregate A and combines with binary operator P to produce value V.

split : A [B] -> A1 A2

Uses test B to split aggregate A into same type aggregates A1 and A2.

(Note: Preserves stack state before each test is run, restoring it after).

Recursion

primrec : X [I] [C] -> R

Executes I to obtain an initial value R0. For integer X uses increasing positive integers to X, combines by C for new R. For aggregate X uses successive members and combines by C for new R.

The primrec combinator expects two quoted programs in addition to a data parameter. For an integer data parameter it works like this: If the data parameter is zero, then the first quotation has to produce the value to be returned. If the data parameter is positive then the second has to combine the data parameter with the result of applying the function to its predecessor. For the factorial function the required quoted programs are very simple:

[1] [*] primrec

computes the factorial recursively. There is no need for any definition. For example, the following program computes the factorial of 5:

5 [1] [*] primrec

It first pushes the number 5 and then it pushes the two short quoted programs. At this point the stack contains three elements. Then the primrec combinator is executed. It pops the two quotations off the stack and saves them elsewhere. Then primrec tests whether the top element on the stack (initially the 5) is equal to zero. If it is, it pops it off and executes one of the quotations, the [1] which leaves 1 on the stack as the result. Otherwise it pushes a decremented copy of the top element and recurses. On the way back from the recursion it uses the other quotation, [*], to multiply what is now a factorial on top of the stack by the second element on the stack. When all is done, the stack contains 120, the factorial of 5. As may be seen from this program, the usual branching of recursive definitions is built into the combinator. The primrec combinator can be used with many other quotation parameters to compute quite different functions. It can also be used with data types other than integers.

linrec : [P] [T] [R1] [R2] -> ...

Executes P. If that yields true, executes T. Else executes R1, recurses, executes R2.

A high proportion of recursively defined functions exhibit a very simple pattern: There is some test, the if-part, which determines whether the ground case obtains. If it does, then the non-recursive branch is executed, the basis case of recursion. If it does not, then the recursive part is executed, including one or more recursive calls.

The linrec combinator is very similar to the genrec combinator. The essential difference is that the bundled up quotation is immediately called before the rec2-part. Consequently it can only be used for linear recursion.

binrec : [B] [T] [R1] [R2] -> ...

Executes B. If that yields true, executes T. Else uses R1 to produce two intermediates, recurses on both, then executes R2 to combines their results.

In many recursive definitions there are two recursive calls of the function being defined. This is the pattern of binary recursion, and it is used in the usual definitions of quicksort and of the Fibonacci function. In analogy with the linrec combinator for linear recursion, Joy has a binrec combinator for binary recursion. The following will quicksort a list whose members can be a mixture of anything except lists:

quicksort ==
  [small]
  []
  [uncons [>] split]
  [swapd cons concat]
  binrec;

And an example using the above quicksort:

[5 3 1 4 2] quicksort => [1 2 3 4 5]

genrec : [B] [T] [R1] [R2] -> ...

Executes B, if that yields true executes T. Else executes R1 and then [[B] [T] [R1] [R2] genrec] R2.

One of these is the genrec combinator which takes four program parameters in addition to whatever data parameters it needs. Fourth from the top is an if-part, followed by a then-part. If the if-part yields true, then the then-part is executed and the combinator terminates. The other two parameters are the rec1-part and the rec2part. If the if-part yields false, the rec1-part is executed. Following that the four program parameters and the combinator are again pushed onto the stack bundled up in a quoted form. Then the rec2-part is executed, where it will find the bundled form. Typically it will then execute the bundled form, either with i or with app2, or some other combinator. The following pieces of code, without any definitions, compute the factorial, the (naive) Fibonacci and quicksort. The four parts are here aligned to make comparisons easier.

Input/Output

rand : -> I

I is a random integer.

Control Flow

ifte : [B] [T] [F] -> ...

Preserves the stack state, then executes B. The stack state is then restored. If B yielded true, then executes T else executes F.

Put another way, it saves the stack before calling the conditional and restores it before calling the appropriate branch, therefore hiding any changing of the stack the conditional may have done.

Definitions and Symbols

body : U -> [P]

Quotation [P] is the body of user-defined symbol U.

Example:

• double == 2 *; [double] first body => [2 *]

Ode only:

User-defined symbol U can be a name or a name in a list.

Basic Stack Operations

id : ->

Identity function, does nothing. Any program of the form P id Q is equivalent to just P Q.

dup : X -> X X

Pushes an extra copy of X onto stack.

swap : X Y -> Y X

Interchanges X and Y on top of the stack.

rollup : X Y Z -> Z X Y

Moves X and Y up, moves Z down

rolldown : X Y Z -> Y Z X

Moves Y and Z down, moves X up.

rotate : X Y Z -> Z Y X

Interchanges X and Z.

pop : X ->

Removes X from top of the stack.

dip : X [P] -> ... X

Saves X, executes P, pushes X back.

Advanced Stack Operations

newstack : ... ->

Removes all items from the stack.

stack : .. X Y Z -> .. X Y Z [Z Y X ..]

Pushes the stack as a list.

(Note that when treating lists as stacks, the first element in the list will be the top item of the stack.)

unstack : [X Y ..] -> ..Y X

The list [X Y ..] becomes the new stack.

(Note that when treating lists as stacks, the first element in the list will be the top item of the stack.)

infra : L1 [P] -> L2

Using list L1 as stack, executes P and returns a new list L2. The first element of L1 is used as the top of stack, and after execution of P the top of stack becomes the first element of L2.

(Note that when treating lists as stacks, the first element in the list will be the top item of the stack.)

unary : X [P] -> R

Executes P, which leaves R on top of the stack. No matter how many parameters this consumes, exactly one is removed from the stack.

unary2 : X1 X2 [P] -> R1 R2

Executes P twice, with X1 and X2 on top of the stack. Returns the two values R1 and R2.

unary3 : X1 X2 X3 [P] -> R1 R2 R3

Executes P three times, with Xi, returns Ri (i = 1..3).

unary4 : X1 X2 X3 X4 [P] -> R1 R2 R3 R4

Executes P four times, with Xi, returns Ri (i = 1..4).

Not Yet Implemented

These operators are part of Joy, but have not yet been implemented.

undefs : -> [...]

Push a list of all undefined symbols in the current symbol table.

strtol : S I -> J

String S is converted to the integer J using base I. If I = 0, assumes base 10, but leading "0" means base 8 and leading "0x" means base 16.

strtod : S -> R

String S is converted to the float R.

format : N C I J -> S

S is the formatted version of N in mode C ('d or 'i = decimal, 'o = octal, 'x or 'X = hex with lower or upper case letters) with maximum width I and minimum width J.

formatf : F C I J -> S

S is the formatted version of F in mode C ('e or 'E = exponential, 'f = fractional, 'g or G = general with lower or upper case letters) with maximum width I and precision J.

srand : I ->

Sets the random integer seed to integer I.

max : N1 N2 -> N

N is the maximum of numeric values N1 and N2. Also supports float.

min : N1 N2 -> N

N is the minimum of numeric values N1 and N2. Also supports float.

compare : A B -> I

I (=-1,0,+1) is the comparison of aggregates A and B. The values correspond to the predicates <=, =, >=.

at : A I -> X

X (= A[I]) is the member of A at position I.

of : I A -> X

X (= A[I]) is the I-th member of aggregate A.

opcase : X [..[X Xs]..] -> [Xs]

Indexing on type of X, returns the list [Xs].

case : X [..[X Y]..] -> Y i

Indexing on the value of X, execute the matching Y.

unswons : A -> R F

R and F are the rest and the first of non-empty aggregate A.

drop : A N -> B

Aggregate B is the result of deleting the first N elements of A.

take : A N -> B

Aggregate B is the result of retaining just the first N elements of A.

enconcat : X S T -> U

Sequence U is the concatenation of sequences S and T with X inserted between S and T (== swapd cons concat)

equal : T U -> B

(Recursively) tests whether trees T and U are identical.

has : A X -> B

Tests whether aggregate A has X as a member.

in : X A -> B

Tests whether X is a member of aggregate A.

leaf : X -> B

Tests whether X is not a list.

user : X -> B

Tests whether X is a user-defined symbol.

file : F -> B

Tests whether F is a file.

x : [P]i -> ...

Executes P without popping [P]. So, [P] x == [P] P.

app1 : X [P] -> R

Executes P, pushes result R on stack without X.

app11 : X Y [P] -> R

Executes P, pushes result R on stack.

app12 : X Y1 Y2 [P] -> R1 R2

Executes P twice, with Y1 and Y2, returns R1 and R2.

construct : [P] [[P1] [P2] ..] -> R1 R2 ..

Saves state of stack and then executes [P]. Then executes each [Pi] to give Ri pushed onto saved stack.

nullary : [P] -> R

Executes P, which leaves R on top of the stack. No matter how many parameters this consumes, none are removed from the stack.

binary : X Y [P] -> R

Executes P, which leaves R on top of the stack. No matter how many parameters this consumes, exactly two are removed from the stack.

ternary : X Y Z [P] -> R

Executes P, which leaves R on top of the stack. No matter how many parameters this consumes, exactly three are removed from the stack.

cleave : X [P1] [P2] -> R1 R2

Executes P1 and P2, each with X on top, producing two results.

branch : B [T] [F] -> ...

If B is true, then executes T else executes F.

ifinteger : X [T] [E] -> ...

If X is an integer, executes T else executes E.

ifchar : X [T] [E] -> ...

If X is a character, executes T else executes E.

iflogical : X [T] [E] -> ...

If X is a logical or truth value, executes T else executes E.

ifset : X [T] [E] -> ...

If X is a set, executes T else executes E.

ifstring : X [T] [E] -> ...

If X is a string, executes T else executes E.

iflist : X [T] [E] -> ...

If X is a list, executes T else executes E.

iffloat : X [T] [E] -> ...

If X is a float, executes T else executes E.

iffile : X [T] [E] -> ...

If X is a file, executes T else executes E.

cond : [..[[Bi] Ti]..[D]] -> ...

Tries each Bi. If that yields true, then executes Ti and exits. If no Bi yields true, executes default D.

while : [B] [D] -> ...

While executing B yields true executes D.

tailrec : [P] [T] [R1] -> ...

Executes P. If that yields true, executes T. Else executes R1, recurses.

condlinrec : [ [C1] [C2] .. [D] ] -> ...

Each [Ci] is of the forms [[B] [T]] or [[B] [R1] [R2]]. Tries each B. If that yields true and there is just a [T], executes T and exit. If there are [R1] and [R2], executes R1, recurses, executes R2. Subsequent case are ignored. If no B yields true, then [D] is used. It is then of the forms [[T]] or [[R1] [R2]]. For the former, executes T. For the latter executes R1, recurses, executes R2.

step : A [P] -> ...

Sequentially putting members of aggregate A onto stack, executes P for each member of A.

times : N [P] -> ...

N times executes P.

filter : A [B] -> A1

Uses test B to filter aggregate A producing sametype aggregate A1.

some : A [B] -> X

Applies test B to members of aggregate A, X = true if some pass.

all : A [B] -> X

Applies test B to members of aggregate A, X = true if all pass.

treestep : T [P] -> ...

Recursively traverses leaves of tree T, executes P for each leaf.

treerec : T [O] [C] -> ...

T is a tree. If T is a leaf, executes O. Else executes [[O] [C] treerec] C.

treegenrec : T [O1] [O2] [C] -> ...

T is a tree. If T is a leaf, executes O1. Else executes O2 and then [[O1] [O2] [C] treegenrec] C.

neg : I -> J

Integer J is the negative of integer I. Also supports float.

ord : C -> I

Integer I is the Ascii value of character C (or logical or integer).

chr : I -> C

C is the character whose Ascii value is integer I (or logical or character).

abs : N1 -> N2

Integer N2 is the absolute value (0,1,2..) of integer N1, or float N2 is the absolute value (0.0 ..) of float N1

acos : F -> G

G is the arc cosine of F.

asin : F -> G

G is the arc sine of F.

atan : F -> G

G is the arc tangent of F.

atan2 : F G -> H

H is the arc tangent of F / G.

ceil : F -> G

G is the float ceiling of F.

cos : F -> G

G is the cosine of F.

cosh : F -> G

G is the hyperbolic cosine of F.

exp : F -> G

G is e (2.718281828...) raised to the Fth power.

floor : F -> G

G is the floor of F.

frexp : F -> G I

G is the mantissa and I is the exponent of F. Unless F = 0, 0.5 <= abs(G) < 1.0.

ldexp : F I -> G

G is F times 2 to the Ith power.

log : F -> G

G is the natural logarithm of F.

log10 : F -> G

G is the common logarithm of F.

modf : F -> G H

G is the fractional part and H is the integer part (but expressed as a float) of F.

pow : F G -> H

H is F raised to the Gth power.

sin : F -> G

G is the sine of F.

sinh : F -> G

G is the hyperbolic sine of F.

sqrt : F -> G

G is the square root of F.

tan : F -> G

G is the tangent of F.

tanh : F -> G

G is the hyperbolic tangent of F.

trunc : F -> I

I is an integer equal to the float F truncated toward zero.

Notes on Joy

These operators are mentioned occassionally in Joy examples, but have been replaced by new operations by Manfred von Thun, original author of Joy, himself.

app2 : X1 X2 [P] -> R1 R2

Obsolescent. == unary2

app3 : X1 X2 X3 [P] -> R1 R2 R3

Obsolescent. == unary3

app4 : X1 X2 X3 X4 [P] -> R1 R2 R3 R4

Obsolescent. == unary4

Other Operations (Not Implemented)

conts : -> [[P] [Q] ..]

Pushes current continuations. Buggy, do not use.

autoput : -> I

Pushes current value of flag for automatic output, I = 0..2.

undeferror : -> I

Pushes current value of undefined-is-error flag.

echo : -> I

Pushes value of echo flag, I = 0..3.

clock : -> I

Pushes the integer value of current CPU usage in hundreds of a second.

time : -> I

Pushes the current time (in seconds since the Epoch).

maxint : -> N

Pushes largest integer (platform dependent). Typically it is 32 bits.

sign : N1 -> N2

Integer N2 is the sign (-1 or 0 or +1) of integer N1, or float N2 is the sign (-1.0 or 0.0 or 1.0) of float N1.

localtime : I -> T

Converts a time I into a list T representing local time: [year month day hour minute second isdst yearday weekday]. Month is 1 = January ... 12 = December; isdst is a Boolean flagging daylight savings/summer time; weekday is 0 = Monday ... 7 = Sunday.

gmtime : I -> T

Converts a time I into a list T representing universal time: [year month day hour minute second isdst yearday weekday]. Month is 1 = January ... 12 = December; isdst is false; weekday is 0 = Monday ... 7 = Sunday.

mktime : T -> I

Converts a list T representing local time into a time I. T is in the format generated by localtime.

strftime : T S1 -> S2

Formats a list T in the format of localtime or gmtime using string S1 and pushes the result S2.

File I/O (Not Implemented)

File Literals

The type of references to open I/O streams, typically but not necessarily files. The only literals of this type are stdin, stdout, and stderr.

get : -> F

Reads a factor from input and pushes it onto stack.

put : X ->

Writes X to output, pops X off stack.

putch : N ->

N : numeric, writes character whose ASCII is N.

putchars : "abc.." ->

Writes abc.. (without quotes)

fclose : S ->

Stream S is closed and removed from the stack.

feof : S -> S B

B is the end-of-file status of stream S.

ferror : S -> S B

B is the error status of stream S.

fflush : S -> S

Flush stream S, forcing all buffered output to be written.

fgetch : S -> S C

C is the next available character from stream S.

fgets : S -> S L

L is the next available line (as a string) from stream S.

fopen : P M -> S

The file system object with pathname P is opened with mode M (r, w, a, etc.) and stream object S is pushed; if the open fails, file:NULL is pushed.

fread : S I -> S L

I bytes are read from the current position of stream S and returned as a list of I integers.

fwrite : S L -> S

A list of integers are written as bytes to the current position of stream S.

fremove : P -> B

The file system object with pathname P is removed from the file system. is a boolean indicating success or failure.

frename : P1 P2 -> B

The file system object with pathname P1 is renamed to P2. B is a boolean indicating success or failure.

fput : S X -> S

Writes X to stream S, pops X off stack.

fputch : S C -> S

The character C is written to the current position of stream S.

fputchars : S "abc.." -> S

The string abc.. (no quotes) is written to the current position of stream S.

fputstring : S "abc.." -> S

== fputchars, as a temporary alternative.

fseek : S P W -> S

Stream S is repositioned to position P relative to whence-point W, where W = 0, 1, 2 for beginning, current position, end respectively.

ftell : S -> S I

I is the current position of stream S.

Sets (Not Implemented)

setsize : -> N

Pushes the maximum number of elements in a set (platform dependent). Typically it is 32, and set members are in the range 0..31.

or : X Y -> Z

Z is the union of sets X and Y.

xor : X Y -> Z

Z is the symmetric difference of sets X and Y.

and : X Y -> Z

Z is the intersection of sets X and Y.

not : X -> Y

Y is the complement of set X.

System Specific Operations (Not Implemented)

These operations do not make sense in the current web-based environment, so are not currently implemented.

help : ->

Lists all defined symbols, including those from library files. Then lists all primitives of raw Joy (There is a variant: "_help" which lists hidden symbols).

helpdetail : [ S1 S2 .. ]

Gives brief help on each symbol S in the list.

manual : ->

Writes this manual of all Joy primitives to output file.

setautoput : I ->

Sets value of flag for automatic put to I (if I = 0, none; if I = 1, put; if I = 2, stack.

setundeferror : I ->

Sets flag that controls behavior of undefined functions (0 = no error, 1 = error).

setecho : I ->

Sets value of echo flag for listing. I = 0: no echo, 1: echo, 2: with tab, 3: and linenumber.

gc : ->

Initiates garbage collection.

system : "command" ->

Escapes to shell, executes string "command". The string may cause execution of another program. When that has finished, the process returns to Joy.

getenv : "variable" -> "value"

Retrieves the value of the environment variable "variable".

argv : -> A

Creates an aggregate A containing the interpreter's command line arguments.

argc : -> I

Pushes the number of command line arguments. This is quivalent to 'argv size'.

include : "filnam.ext" ->

Transfers input to file whose name is "filnam.ext". On end-of-file returns to previous input file.

abort : ->

Aborts execution of current Joy program, returns to Joy main cycle.

quit : ->

Exit from Joy.