Version -10.0.0
Each function, combinator, or definition should be documented here.
See and.
Function
Return the absolute value of the argument.
+dup 0 < [] [neg] branch +
dup 0 < [] [neg] branch
Basis Function
Add two numbers together: a + b.
Combinator
Short-circuiting Boolean AND
Accept two quoted programs, run the first and expect a Boolean value, if it’s true pop it and run the second program (which should also return a Boolean value) otherwise pop the second program (leaving false on the stack.)
true
false
nulco [nullary [false]] dip branch
TODO: this is derived in one of the notebooks I think, look it up and link to it, or copy the content here.
||
Build a list of values from a generator program G and a stopping predicate P.
G
P
[P] [G] anamorphism +----------------------------------------- + [P] [pop []] [G] [dip swons] genrec
+[pop []] swap [dip swons] genrec +
[pop []] swap [dip swons] genrec
The range function generates a list of the integers from 0 to n - 1:
range
+[0 <=] [-- dup] anamorphism +
[0 <=] [-- dup] anamorphism
See the Recursion Combinators notebook.
Logical bit-wise AND.
or xor
“apply one”
Given a quoted program on TOS and anything as the second stack item run the program without disturbing the stack and replace the two args with the first result of the program.
... x [Q] app1 +--------------------------------- + ... [x ...] [Q] infra first
This is the same effect as the unary combinator.
+nullary popd +
nullary popd
Just a specialization of nullary really. Its parallelizable cousins are more useful.
nullary
app2 app3 appN unary
Like app1 with two items.
... y x [Q] . app2 +----------------------------------- + ... [y ...] [Q] . infra first + [x ...] [Q] infra first
+[grba swap grba swap] dip [infrst] cons ii +
[grba swap grba swap] dip [infrst] cons ii
Unlike app1, which is essentially an alias for unary, this function is not the same as binary. Instead of running one program using exactly two items from the stack and pushing one result (as binary does) this function takes two items from the stack and runs the program twice, separately for each of the items, then puts both results onto the stack.
This is not currently implemented as parallel processes but it can (and should) be done.
app1 app3 appN unary
Like app1 with three items.
... z y x [Q] . app3 +----------------------------------- + ... [z ...] [Q] . infra first + [y ...] [Q] infra first + [x ...] [Q] infra first
+3 appN +
3 appN
See app2.
app1 app2 appN unary
Like app1 with any number of items.
... xN ... x2 x1 x0 [Q] n . appN +-------------------------------------- + ... [xN ...] [Q] . infra first + ... + [x2 ...] [Q] infra first + [x1 ...] [Q] infra first + [x0 ...] [Q] infra first
+[grabN] codi map disenstacken +
[grabN] codi map disenstacken
This function takes a quoted function Q and an integer and runs the function that many times on that many stack items. See also app2.
Q
app1 app2 app3 unary
See mul.
See getitem.
Compute the average of a list of numbers. (Currently broken until I can figure out what to do about “numeric tower” in Thun.)
+[sum] [size] cleave / +
[sum] [size] cleave /
Theoretically this function would compute the sum and the size in two separate threads, then divide. This works but a compiled version would probably do better to sum and count the list once, in one thread, eh?
As an exercise in Functional Programming in Joy it would be fun to convert this into a catamorphism. See the Recursion Combinators notebook.
Run a quoted program using exactly two stack values and leave the first item of the result on the stack.
... y x [P] binary +----------------------- + ... a
+unary popd +
unary popd
Runs any other quoted function and returns its first result while consuming exactly two items from the stack.
nullary ternary unary
Run two quoted programs
[P] [Q] b +--------------- + P Q
+[i] dip i +
[i] dip i
This combinator may seem trivial but it comes in handy.
dupdip ii
Convert the item on the top of the stack to a Boolean value.
For integers 0 is false and any other number is true; for lists the empty list is false and all other lists are true.
not
Basis Combinator
Use a Boolean value to select and run one of two quoted programs.
false [F] [T] branch +-------------------------- + F + + true [F] [T] branch +------------------------- + T
+rolldown choice i +
rolldown choice i
This is one of the fundamental operations (although it can be defined in terms of choice as above). The more common “if..then..else” construct ifte adds a predicate function that is evaluated nullary.
choice ifte select
See id.
a b c d [...] ccccons +--------------------------- + [a b c d ...]
Do cons four times.
+ccons ccons +
ccons ccons
ccons cons times
a b [...] ccons +--------------------- + [a b ...]
Do cons two times.
+cons cons +
cons cons
cons ccons
Use a Boolean value to select one of two items.
a b false choice +---------------------- + a + + a b true choice +--------------------- + b
+[pop] [popd] branch +
[pop] [popd] branch
It’s a matter of taste whether you implement this in terms of branch or the other way around.
branch select
See xor.
Clear everything from the stack.
+stack bool [pop stack bool] loop +
stack bool [pop stack bool] loop
stack swaack
Run two programs in parallel, consuming one additional item, and put their results on the stack.
... x [A] [B] cleave +------------------------ + ... a b
+fork popdd +
fork popdd
1 2 3 [+] [-] cleave +-------------------------- + 1 2 5 -1
One of a handful of useful parallel combinators.
clop fork map
Run two programs in parallel, consuming two additional items, and put their results on the stack.
... x y [A] [B] clop +-------------------------- + ... a b
+cleave popdd +
cleave popdd
Like cleave but consumes an additional item from the stack.
1 2 3 4 [+] [-] clop +-------------------------- + 1 2 7 -1
cleave fork map
Take two values and three quoted programs on the stack and run one of the three depending on the results of comparing the two values.
a b [G] [E] [L] cmp +------------------------- a > b + G + + a b [G] [E] [L] cmp +------------------------- a = b + E + + a b [G] [E] [L] cmp +------------------------- a < b + L
This is useful sometimes, and you can dup or dupd with two quoted programs to handle the cases when you just want to deal with <= or >= and not all three possibilities, e.g.:
[G] [EL] dup cmp + +[GE] [L] dupd cmp
Or even:
[GL] [E] over cmp
TODO: link to tree notebooks where this was used.
Take a quoted program from the stack, cons the next item onto it, then dip the whole thing under what was the third item on the stack.
a b [F] . codi +-------------------- + b . F a
+cons dip +
cons dip
This is one of those weirdly specific functions that turns out to be useful in a few places.
appN codireco
This is part of the make_generator function. You would not use this combinator directly.
+codi reco +
codi reco
See make_generator and the “Using x to Generate Values” notebook as well as Recursion Theory and Joy by Manfred von Thun.
x
make_generator
Concatinate two lists.
[a b c] [d e f] concat +---------------------------- + [a b c d e f]
first first_two flatten fourth getitem remove rest reverse rrest second shift shunt size sort split_at split_list swaack third zip
This combinator works like a case statement. It expects a single quote on the stack that must contain zero or more condition quotes and a default quote. Each condition quote should contain a quoted predicate followed by the function expression to run if that predicate returns true. If no predicates return true the default function runs.
[ + [ [Predicate0] Function0 ] + [ [Predicate1] Function1 ] + ... + [ [PredicateN] FunctionN ] + [Default] +] +cond
It works by rewriting into a chain of nested ifte expressions, e.g.:
[[[B0] T0] [[B1] T1] [D]] cond +----------------------------------------- + [B0] [T0] [[B1] [T1] [D] ifte] ifte
ifte
Given an item and a list, append the item to the list to make a new list.
a [...] cons +------------------ + [a ...]
Cons is a venerable old function from Lisp. Its inverse operation is uncons.
uncons
Specialist function (that means I forgot what it does and why.)
+dip infrst +
dip infrst
Like dip but expects three items. :
... z y x [Q] . dip +----------------------------- + ... . Q z y x
See dip.
dip dipd dupdip dupdipd infra
Like dip but expects two items.
... y x [Q] . dipd +------------------------- + ... . Q y x
dip dipdd dupdip dupdipd infra
The dip combinator expects a quoted program on the stack and below it some item, it hoists the item into the expression and runs the program on the rest of the stack.
dip
... x [Q] . dip +--------------------- + ... . Q x
This along with infra are enough to update any datastructure. See the “Traversing Datastructures with Zippers” notebook.
Note that the item that was on the top of the stack (x in the example above) will not be treated specially by the interpreter when it is reached again. This is something of a footgun. My advice is to avoid putting bare unquoted symbols onto the stack, but then you can’t use symbols as “atoms” and also use dip and infra to operate on compound datastructures with atoms in them. This is a kind of side-effect of the Continuation-Passing Style. The dip combinator could “set aside” the item and replace it after running Q but that means that there is an “extra space” where the item resides while Q runs. One of the nice things about CPS is that the whole state is recorded in the stack and pending expression (not counting modifications to the dictionary.)
infra
dipd dipdd dupdip dupdipd infra
The disenstacken function expects a list on top of the stack and makes that the stack discarding the rest of the stack.
disenstacken
1 2 3 [4 5 6] disenstacken +-------------------------------- + 6 5 4
+[clear] dip reverse unstack +
[clear] dip reverse unstack
Note that the order of the list is not changed, it just looks that way because the stack is printed with the top on the right while lists are printed with the top or head on the left.
enstacken stack unstack
See floordiv.
x y divmod +------------------ + q r + (x/y) (x%y)
Invariant: qy + r = x.
qy + r = x
+[floordiv] [mod] clop +
[floordiv] [mod] clop
Given a number greater than zero put all the Natural numbers (including zero) less than that onto the stack.
3 down_to_zero +-------------------- + 3 2 1 0
+[0 >] [dup –] while +
[0 >] [dup –] while
Expects an integer and a quote on the stack and returns the quote with n items removed off the top.
[a b c d] 2 drop +---------------------- + [c d]
+[rest] times +
[rest] times
take
dup the third item down on the stack.
a b c dupdd +----------------- + a a b c
+[dup] dipd +
[dup] dipd
dup dupd dupdip dupdipd
Run a copy of program F under the next item down on the stack.
F
a [F] dupdipd +------------------- + F a [F]
+dup dipd +
dup dipd
dupdip
Apply a function F and dup the item under it on the stack.
a [F] dupdip +------------------ + a F a
+dupd dip +
dupd dip
a [F] dupdip +a [F] dupd dip +a [F] [dup] dip dip +a dup [F] dip +a a [F] dip +a F a
A very common and useful combinator.
dupdipd
dup the second item down on the stack.
a b dupd +-------------- + a a b
+[dup] dip +
[dup] dip
dup dupdd dupdip dupdipd
“Dup”licate the top item on the stack.
a dup +----------- + a a
dupd dupdd dupdip dupdipd
Put the stack onto the stack replacing the contents of the stack.
... a b c enstacken +------------------------- + [c b a ...]
+stack [clear] dip +
stack [clear] dip
This is a destructive version of stack. See the note under disenstacken about the apparent but illusory reversal of the stack.
stack [unstack] disenstacken
Compare the two items on the top of the stack for equality and replace them with a Boolean value.
a b eq +------------- + Boolean + (a = b)
cmp ge gt le lt ne
See eq.
0 \>=
Return a Boolean value indicating if a number is greater than or equal to zero.
See gt.
See ge.
See rshift.
See sub.
See pred.
See lt.
See le.
See ne.
... a <{} ----------------- - ... [] a
[] swap
Tuck an empty list just under the first item on the stack.
<<{}
See lshift.
... b a <{} ------------------ - ... [] b a
[] rollup
Tuck an empty list just under the first two items on the stack.
<{}
See mod.
See add.
See succ.
Is the item on the top of the stack “truthy”?
-dup bool -
dup bool
You often want to test the truth value of an item on the stack without consuming the item.
bool
Short-circuiting Boolean OR
-nulco [nullary] dip [true] branch -
nulco [nullary] dip [true] branch
Accept two quoted programs, run the first and expect a Boolean value, if it’s false pop it and run the second program (which should also return a Boolean value) otherwise pop the second program (leaving true on the stack.)
[A] [B] || ----------------- A -> false - B - - - [A] [B] || ----------------- A -> true - true
&&
-dup 0 < [] [neg] branch -
[P] [G] anamorphism ------------------------------------------ - [P] [pop []] [G] [dip swons] genrec
-[pop []] swap [dip swons] genrec -
-[0 <=] [-- dup] anamorphism -
... x [Q] app1 ---------------------------------- - ... [x ...] [Q] infra first
-nullary popd -
... y x [Q] . app2 ------------------------------------ - ... [y ...] [Q] . infra first - [x ...] [Q] infra first
-[grba swap grba swap] dip [infrst] cons ii -
... z y x [Q] . app3 ------------------------------------ - ... [z ...] [Q] . infra first - [y ...] [Q] infra first - [x ...] [Q] infra first
-3 appN -
... xN ... x2 x1 x0 [Q] n . appN --------------------------------------- - ... [xN ...] [Q] . infra first - ... - [x2 ...] [Q] infra first - [x1 ...] [Q] infra first - [x0 ...] [Q] infra first
-[grabN] codi map disenstacken -
-[sum] [size] cleave / -
[P] [Q] b ---------------- - P Q
-[i] dip i -
... y x [P] binary ------------------------ - ... a
-unary popd -
false [F] [T] branch --------------------------- - F - - true [F] [T] branch -------------------------- - T
-rolldown choice i -
a b c d [...] ccccons ---------------------------- - [a b c d ...]
-ccons ccons -
a b [...] ccons ---------------------- - [a b ...]
-cons cons -
a b false choice ----------------------- - a - - a b true choice ---------------------- - b
-[pop] [popd] branch -
-stack bool [pop stack bool] loop -
... x [A] [B] cleave ------------------------- - ... a b
-fork popdd -
1 2 3 [+] [-] cleave --------------------------- - 1 2 5 -1
... x y [A] [B] clop --------------------------- - ... a b
-cleave popdd -
1 2 3 4 [+] [-] clop --------------------------- - 1 2 7 -1
a b [G] [E] [L] cmp -------------------------- a > b - G - - a b [G] [E] [L] cmp -------------------------- a = b - E - - a b [G] [E] [L] cmp -------------------------- a < b - L
[G] [EL] dup cmp - -[GE] [L] dupd cmp
a b [F] . codi --------------------- - b . F a
-cons dip -
-codi reco -
[a b c] [d e f] concat ----------------------------- - [a b c d e f]
[ - [ [Predicate0] Function0 ] - [ [Predicate1] Function1 ] - ... - [ [PredicateN] FunctionN ] - [Default] -] -cond
[[[B0] T0] [[B1] T1] [D]] cond ------------------------------------------ - [B0] [T0] [[B1] [T1] [D] ifte] ifte
a [...] cons ------------------- - [a ...]
-dip infrst -
... x [Q] . dip ---------------------- - ... . Q x
... y x [Q] . dipd -------------------------- - ... . Q y x
... z y x [Q] . dip ------------------------------ - ... . Q z y x
1 2 3 [4 5 6] disenstacken --------------------------------- - 6 5 4
-[clear] dip reverse unstack -
x y divmod ------------------- - q r - (x/y) (x%y)
-[floordiv] [mod] clop -
3 down_to_zero --------------------- - 3 2 1 0
-[0 >] [dup –] while -
[a b c d] 2 drop ----------------------- - [c d]
-[rest] times -
a dup ------------ - a a
a b dupd --------------- - a a b
-[dup] dip -
a b c dupdd ------------------ - a a b c
-[dup] dipd -
a [F] dupdip ------------------- - a F a
-dupd dip -
a [F] dupdip -a [F] dupd dip -a [F] [dup] dip dip -a dup [F] dip -a a [F] dip -a F a
a [F] dupdipd -------------------- - F a [F]
-dup dipd -
... a b c enstacken -------------------------- - [c b a ...]
-stack [clear] dip -
a b eq -------------- - Boolean - (a = b)
[a ...] -------------- a
uncons pop
second third fourth rest
[a b ...] first_two ------------------------- a b
uncons first
first second third fourth rest
[[1 2] [3 [4] 5] [6 7]] flatten ------------------------------------- [1 2 3 [4] 5 6 7]
-<{} [concat] step +<{} [concat] step
<{} [concat] step
Note that only one “level” of lists is flattened. In the example above [4] is not unquoted.
[4]
concat first first_two fourth getitem remove rest reverse rrest second shift shunt size sort split_at split_list swaack third zip
Return the largest integer <= x.
This function doesn’t make sense (yet) to have because there are (as yet) only integers in the system.
I don’t know why this is called “floor” div, I think it rounds its result down (not towards zero or up.)
a b floordiv ------------------ (a/b)
All the division commands need to be revisited when the “numeric tower” for Thun gets nailed down.
divmod
Run two quoted programs in parallel and replace them with their results.
... [F] [G] fork ---------------------- ... f g
[i] app2
The basic parallelism combinator, the two programs are run independently.
cleave clop map
[a b c d ...] fourth -------------------------- d
rest third
first second third rest
Take two integers from the stack and replace them with their Greatest Common Denominator.
-true [tuck mod dup 0 >] loop pop -
true [tuck mod dup 0 >] loop pop
Euclid’s Algorithm
Compiled GCD function.
See gcd.
gcd
+true [tuck mod dup 0 >] loop pop +
Greater-than-or-equal-to comparison of two numbers.
cmp eq gt le lt ne
[if] [then] [rec1] [rec2] genrec --------------------------------------------------------------------- [if] [then] [rec1 [[if] [then] [rec1] [rec2] genrec] rec2] ifte
[[genrec] ccccons] nullary swons concat ifte
(Note that this definition includes the genrec symbol itself, it is self-referential. This is possible because the definition machinery does not check that symbols in defs are in the dictionary. genrec is the only self-referential definition.)
genrec
From “Recursion Theory and Joy” by Manfred von Thun:
@@ -1203,7 +967,7 @@ a F a P == [I] [T] [R] tailrec == [I] [T] [R [P] i] ifte == [I] [T] [R P] ifte -Crosslinks +Crosslinks anamorphism tailrec x getitem @@ -1213,13 +977,13 @@ a F a [a b c d] 2 getitem ------------------------- c -Definition +Definition drop first -Discussion +Discussion If the number isn’t a valid index into the quote getitem will cause some sort of problem (the exact nature of which is implementation-dependant.) -Crosslinks +Crosslinks concat first first_two flatten fourth remove rest reverse rrest second shift shunt size sort split_at split_list swaack third zip grabN @@ -1229,9 +993,9 @@ a F a a b c d e 3 grabN ----------------------- a b [c d e] -Definition +Definition -<{} [cons] times +<{} [cons] times grba @@ -1241,15 +1005,24 @@ a F a ------------------------------- ... 1 2 3 [4 3 2 1 ...] 5 It grabs the stack under the top item, and substitutes it for the second item down on the stack. -Definition +Definition [stack popd] dip -Discussion +Discussion This function “grabs” an item from the stack along with a copy of the stack. It’s part of the app2 definition. -Crosslinks +Crosslinks app2 +>= +See ge. + +>> +See rshift. + +> +See gt. + gt Basis Function Greater-than comparison of two numbers. @@ -1257,7 +1030,7 @@ a F a -------------- Boolean (a > b) -Crosslinks +Crosslinks cmp eq ge le lt ne help @@ -1265,36 +1038,33 @@ a F a Accepts a quoted symbol on the top of the stack and prints its documentation. [foo] help ---------------- -Discussion +Discussion Technically this is equivalent to pop, but it will only work if the item on the top of the stack is a quoted symbol. +– +See pred. + +- +See sub. + hypot Function x y hypot --------------------------- sqrt(sqr(x) + sqr(y)) -Definition +Definition [sqr] ii + sqrt -Discussion +Discussion This is another function that has to wait on the numeric tower. -Crosslinks +Crosslinks sqrt -i -Basis Combinator -Append a quoted expression onto the pending expression. - [Q] . i -------------- - . Q -Discussion -This is a fundamental combinator. It is used in all kinds of places. For example, the x combinator can be defined as dup i. - id Basis Function The identity function. -Discussion +Discussion Does nothing. It’s kind of a mathematical thing, but it occasionally comes in handy. ifte @@ -1303,11 +1073,11 @@ a F a [if] [then] [else] ifte --------------------------------------- [if] nullary [else] [then] branch -Definition +Definition [nullary] dipd swap branch -Crosslinks +Crosslinks branch loop while ii @@ -1316,7 +1086,7 @@ a F a ... a [Q] ii ------------------ ... Q a Q -Definition +Definition [dip] dupdip i @@ -1331,7 +1101,7 @@ a F a 1 2 4 4 [++] • i 1 2 4 4 • ++ 1 2 4 5 • -Discussion +Discussion In some cases (like the example above) this is the same effect as using app2 but most of the time it’s not: 1 2 3 4 [+] ii -------------------- @@ -1340,28 +1110,45 @@ a F a 1 2 3 4 [+] app2 ---------------------- 1 2 5 6 -Crosslinks +Crosslinks app2 b +i +Basis Combinator +Append a quoted expression onto the pending expression. + [Q] . i +------------- + . Q +Discussion +This is a fundamental combinator. It is used in all kinds of places. For example, the x combinator can be defined as dup i. + infra Combinator Accept a quoted program and a list on the stack and run the program with the list as its stack. Does not affect the stack (below the list.) ... x y z [a b c] [Q] infra --------------------------------- c b a Q [z y x ...] swaack -Definition +Definition swons swaack [i] dip swaack -Discussion +... [a b c] [F] swons swaack [i] dip swaack +... [[F] a b c] swaack [i] dip swaack + +c b a [F] [...] [i] dip swaack +c b a [F] i [...] swaack +c b a F [...] swaack +d e [...] swaack +... [e d] +Discussion This is one of the more useful combinators. It allows a quoted expression to serve as a stack for a program, effectively running it in a kind of “pocket universe”. If the list represents a datastructure then infra lets you work on its internal structure. -Crosslinks +Crosslinks swaack infrst Combinator Does infra and then extracts the first item from the resulting list. -Definition +Definition infra first @@ -1370,7 +1157,7 @@ a F a Create a new Joy function definition in the Joy dictionary. A definition is given as a quote with a name followed by a Joy expression. Example [sqr dup mul] inscribe -Discussion +Discussion This is the only function that modifies the dictionary. It’s provided as a convenience, for tinkering with new definitions before entering them into the defs.txt file. It can be abused, which you should avoid unless you know what you’re doing. le @@ -1380,9 +1167,45 @@ a F a ------------- Boolean (a <= b) -Crosslinks +Crosslinks cmp eq ge gt lt ne +<= +See le. + +<> +See ne. + +<{} +Function + ... a <{} +---------------- + ... [] a +Definition +[] swap +Discussion +Tuck an empty list just under the first item on the stack. +Crosslinks +<<{} + +<<{} +Function + ... b a <{} +----------------- + ... [] b a +Definition +[] rollup +Discussion +Tuck an empty list just under the first two items on the stack. +Crosslinks +<{} + +<< +See lshift. + +< +See lt. + loop Basis Combinator Expect a quoted program Q and a Boolean value on the stack. If the value is false discard the quoted program, otherwise run a copy of Q and loop again. @@ -1393,13 +1216,13 @@ a F a true [Q] . loop -------------------------- . Q [Q] loop -Discussion +Discussion This, along with branch and fork, is one of the four main combinators of all programming. The fourth, sequence, is implied by juxtaposition. That is to say, in Joy F G is like G(F(...)) in a language bassed on function application. Or again, to quote the Joy Wikipedia entry, In Joy, the meaning function is a homomorphism from the syntactic monoid onto the semantic monoid. That is, the syntactic relation of concatenation of symbols maps directly onto the semantic relation of composition of functions. Anyway, branch, fork, amd loop are the fundamental combinators in Joy. Just as branch has it’s more common and convenient form ifte, loop has while. -Crosslinks +Crosslinks branch fork while lshift @@ -1408,7 +1231,7 @@ a F a a n lshift ---------------- (a×2ⁿ) -Crosslinks +Crosslinks rshift lt @@ -1418,7 +1241,7 @@ a F a ------------- Boolean (a < b) -Crosslinks +Crosslinks cmp eq ge gt le ne make_generator @@ -1435,13 +1258,13 @@ a F a [230 [dup ++] codireco] 5 [x] times pop --------------------------------------------- 230 231 232 233 234 -Definition +Definition [codireco] ccons -Discussion +Discussion See the “Using x to Generate Values” notebook. -Crosslinks +Crosslinks codireco map @@ -1451,9 +1274,9 @@ a F a 5 [1 2 3] [++ *] map -------------------------- 5 [10 15 20] -Discussion +Discussion This is a common operation in many languages. In Joy it can be a parallelism combinator due to the “pure” nature of the language. -Crosslinks +Crosslinks app1 app2 app3 appN fork max @@ -1463,7 +1286,7 @@ a F a [1 2 3 4] max ------------------- 4 -Crosslinks +Crosslinks min size sum min @@ -1473,7 +1296,7 @@ a F a [1 2 3 4] min ------------------- 1 -Crosslinks +Crosslinks max size sum mod @@ -1482,7 +1305,7 @@ a F a a b mod ------------- (a%b) -Crosslinks +Crosslinks divmod mul modulus @@ -1494,9 +1317,20 @@ a F a a b mul ------------- (a×b) -Crosslinks +Crosslinks div product +neg +Function +Invert the sign of a number. + a neg +----------- + -a +Definition + +0 swap - + + ne Basis Function Not-Equal comparison of the two items on the top of the stack, replacing them with a Boolean value. @@ -1504,20 +1338,9 @@ a F a ------------- Boolean (a = b) -Crosslinks +Crosslinks cmp eq ge gt le lt -neg -Function -Invert the sign of a number. - a neg ------------ - -a -Definition - -0 swap - - - not Function Like bool but convert the item on the top of the stack to the inverse Boolean value. @@ -1528,11 +1351,11 @@ a F a false not --------------- true -Definition +Definition bool [true] [false] branch -Crosslinks +Crosslinks bool nulco @@ -1541,14 +1364,14 @@ a F a [F] nulco ------------------- [[F] nullary] -Definition +Definition [nullary] cons -Discussion -Helper function for || and &&. -Crosslinks -&& || +Discussion +Helper function for || and &&. +Crosslinks +&& || nullary Combinator @@ -1556,7 +1379,7 @@ a F a ... [P] nullary --------------------- ... a -Definition +Definition [stack] dip infra first @@ -1567,9 +1390,9 @@ a F a ... [...] [P] infra first ... [a ...] first ... a -Discussion +Discussion A very useful function that runs any other quoted function and returns it’s first result without disturbing the stack (under the quoted program.) -Crosslinks +Crosslinks unary binary ternary of @@ -1579,17 +1402,17 @@ a F a 2 [a b c d] of -------------------- c -Definition +Definition swap getitem -Crosslinks +Crosslinks getitem or Basis Function Logical bit-wise OR. -Crosslinks +Crosslinks and xor over @@ -1598,7 +1421,7 @@ a F a a b over -------------- a b a -Definition +Definition There are many many ways to define this function. swap tuck @@ -1616,9 +1439,9 @@ a F a unit dupdipd first And so on… -Discussion +Discussion A fine old word from Forth. -Crosslinks +Crosslinks tuck pam @@ -1628,29 +1451,64 @@ a F a 5 7 [[+][-][*][/][%]] pam ------------------------------- 5 7 [12 -2 35 0 5] -Definition +Definition [i] map -Discussion +Discussion A specialization of map that runs a list of functions in parallel (if the underlying map function is so implemented, of course.) -Crosslinks +Crosslinks map +% +See mod. + pick See getitem. ++ +See add. + +++ +See succ. + pm Function Plus or minus. Replace two numbers with their sum and difference. a b pm ----------------- (a+b) (a-b) -Definition +Definition [+] [-] clop +popdd +Function +pop the third item on the stack. + a b c popdd +----------------- + b c +Definition + +rolldown pop + +Crosslinks +pop popd popop popopd popopdd popopop + +popd +Function +pop the second item down on the stack. + a b popd +-------------- + b +Definition + +swap pop + +Crosslinks +pop popdd popop popopd popopdd popopop + pop Basis Function Pop the top item from the stack and discard it. @@ -1659,31 +1517,30 @@ a F a Crosslinks popd popdd popop popopd popopdd popopop -popd +popopdd Function -pop the second item down on the stack. - a b popd --------------- - b + a b c d popopdd +--------------------- + c d Definition -swap pop +[popop] dipd Crosslinks -pop popdd popop popopd popopdd popopop +pop popd popdd popop popopd popopop -popdd +popopd Function -pop the third item on the stack. - a b c popdd ------------------ - b c +pop the second and third items from the stack. + a b c popopd +------------------ + c Definition -rolldown pop +rollup popop Crosslinks -pop popd popop popopd popopdd popopop +pop popd popdd popop popopdd popopop popop Function @@ -1697,46 +1554,21 @@ a F a Crosslinks pop popd popdd popopd popopdd popopop -popopd -Function -pop the second and third items from the stack. - a b c popopd ------------------- - c -Definition - -rollup popop - -Crosslinks -pop popd popdd popop popopdd popopop - -popopdd -Function - a b c d popopdd ---------------------- - c d -Definition - -[popop] dipd - -Crosslinks -pop popd popdd popop popopd popopop - popopop Function pop three items from the stack. a b c popopop ------------------- -Definition +Definition pop popop -Crosslinks +Crosslinks pop popd popdd popop popopd popopdd pow Basis Function -Take two numbers a and b from the stack and raise a to the nth power. (b is on the top of the stack.) +Take two numbers a and n from the stack and raise a to the nth power. (n is on the top of the stack.) a n pow ------------- (aⁿ) @@ -1748,11 +1580,11 @@ a F a pred Function Predecessor. Decrement TOS. -Definition +Definition 1 - -Crosslinks +Crosslinks succ primrec @@ -1774,15 +1606,15 @@ a F a n [Base] [Recur] primrec ------------------------------------------ n > 0 n (n-1) [Base] [Recur] primrec Recur -Discussion +Discussion Simple and useful specialization of the genrec combinator from the original Joy system. -Crosslinks +Crosslinks genrec tailrec product Function Just as sum sums a list of numbers, this function multiplies them together. -Definition +Definition 1 swap [mul] step @@ -1791,19 +1623,31 @@ a F a [1] [mul] primrec
P == [I] [T] [R] tailrec == [I] [T] [R [P] i] ifte == [I] [T] [R P] ifte
anamorphism tailrec x
[a b c d] 2 getitem ------------------------- c
drop first
If the number isn’t a valid index into the quote getitem will cause some sort of problem (the exact nature of which is implementation-dependant.)
getitem
concat first first_two flatten fourth remove rest reverse rrest second shift shunt size sort split_at split_list swaack third zip
a b c d e 3 grabN ----------------------- a b [c d e]
-<{} [cons] times +<{} [cons] times
<{} [cons] times
It grabs the stack under the top item, and substitutes it for the second item down on the stack.
[stack popd] dip
This function “grabs” an item from the stack along with a copy of the stack. It’s part of the app2 definition.
app2
Greater-than comparison of two numbers.
cmp eq ge le lt ne
Accepts a quoted symbol on the top of the stack and prints its documentation.
[foo] help ----------------
Technically this is equivalent to pop, but it will only work if the item on the top of the stack is a quoted symbol.
pop
x y hypot --------------------------- sqrt(sqr(x) + sqr(y))
[sqr] ii + sqrt
This is another function that has to wait on the numeric tower.
sqrt
Append a quoted expression onto the pending expression.
[Q] . i -------------- - . Q
This is a fundamental combinator. It is used in all kinds of places. For example, the x combinator can be defined as dup i.
dup i
The identity function.
Does nothing. It’s kind of a mathematical thing, but it occasionally comes in handy.
[if] [then] [else] ifte --------------------------------------- [if] nullary [else] [then] branch
[nullary] dipd swap branch
branch loop while
... a [Q] ii ------------------ ... Q a Q
[dip] dupdip i
In some cases (like the example above) this is the same effect as using app2 but most of the time it’s not:
1 2 3 4 [+] ii -------------------- @@ -1340,28 +1110,45 @@ a F a
app2 b
[Q] . i +------------- + . Q
Accept a quoted program and a list on the stack and run the program with the list as its stack. Does not affect the stack (below the list.)
... x y z [a b c] [Q] infra --------------------------------- c b a Q [z y x ...] swaack
swons swaack [i] dip swaack
... [a b c] [F] swons swaack [i] dip swaack +... [[F] a b c] swaack [i] dip swaack + +c b a [F] [...] [i] dip swaack +c b a [F] i [...] swaack +c b a F [...] swaack +d e [...] swaack +... [e d]
This is one of the more useful combinators. It allows a quoted expression to serve as a stack for a program, effectively running it in a kind of “pocket universe”. If the list represents a datastructure then infra lets you work on its internal structure.
swaack
Does infra and then extracts the first item from the resulting list.
infra first
Create a new Joy function definition in the Joy dictionary. A definition is given as a quote with a name followed by a Joy expression.
[sqr dup mul] inscribe
This is the only function that modifies the dictionary. It’s provided as a convenience, for tinkering with new definitions before entering them into the defs.txt file. It can be abused, which you should avoid unless you know what you’re doing.
defs.txt
cmp eq ge gt lt ne
... a <{} +---------------- + ... [] a
... b a <{} +----------------- + ... [] b a
Expect a quoted program Q and a Boolean value on the stack. If the value is false discard the quoted program, otherwise run a copy of Q and loop again.
loop
This, along with branch and fork, is one of the four main combinators of all programming. The fourth, sequence, is implied by juxtaposition. That is to say, in Joy F G is like G(F(...)) in a language bassed on function application. Or again, to quote the Joy Wikipedia entry,
F G
G(F(...))
In Joy, the meaning function is a homomorphism from the syntactic monoid onto the semantic monoid. That is, the syntactic relation of concatenation of symbols maps directly onto the semantic relation of composition of functions.
Anyway, branch, fork, amd loop are the fundamental combinators in Joy. Just as branch has it’s more common and convenient form ifte, loop has while.
branch fork while
a n lshift ---------------- (a×2ⁿ)
rshift
cmp eq ge gt le ne
[230 [dup ++] codireco] 5 [x] times pop --------------------------------------------- 230 231 232 233 234
[codireco] ccons
See the “Using x to Generate Values” notebook.
codireco
5 [1 2 3] [++ *] map -------------------------- 5 [10 15 20]
This is a common operation in many languages. In Joy it can be a parallelism combinator due to the “pure” nature of the language.
app1 app2 app3 appN fork
[1 2 3 4] max ------------------- 4
min size sum
[1 2 3 4] min ------------------- 1
max size sum
a b mod ------------- (a%b)
divmod mul
a b mul ------------- (a×b)
div product
Invert the sign of a number.
a neg +----------- + -a
+0 swap - +
0 swap -
Not-Equal comparison of the two items on the top of the stack, replacing them with a Boolean value.
cmp eq ge gt le lt
a neg ------------ - -a
-0 swap - -
Like bool but convert the item on the top of the stack to the inverse Boolean value.
bool [true] [false] branch
[F] nulco ------------------- [[F] nullary]
[nullary] cons
Helper function for || and &&.
&& ||
... [P] nullary --------------------- ... a
[stack] dip infra first
A very useful function that runs any other quoted function and returns it’s first result without disturbing the stack (under the quoted program.)
unary binary ternary
2 [a b c d] of -------------------- c
swap getitem
Logical bit-wise OR.
and xor
a b over -------------- a b a
There are many many ways to define this function.
swap tuck @@ -1616,9 +1439,9 @@ a F a unit dupdipd first
swap tuck
unit dupdipd first
And so on…
A fine old word from Forth.
tuck
5 7 [[+][-][*][/][%]] pam ------------------------------- 5 7 [12 -2 35 0 5]
[i] map
A specialization of map that runs a list of functions in parallel (if the underlying map function is so implemented, of course.)
map
Plus or minus. Replace two numbers with their sum and difference.
a b pm ----------------- (a+b) (a-b)
[+] [-] clop
pop the third item on the stack.
a b c popdd +----------------- + b c
+rolldown pop +
rolldown pop
pop popd popop popopd popopdd popopop
pop the second item down on the stack.
a b popd +-------------- + b
+swap pop +
swap pop
pop popdd popop popopd popopdd popopop
Pop the top item from the stack and discard it.
popd popdd popop popopd popopdd popopop
a b popd --------------- - b
a b c d popopdd +--------------------- + c d
-swap pop +[popop] dipd
[popop] dipd
pop popd popdd popop popopd popopop
a b c popdd ------------------ - b c
pop the second and third items from the stack.
a b c popopd +------------------ + c
-rolldown pop +rollup popop
rollup popop
pop popd popdd popop popopdd popopop
pop popd popdd popopd popopdd popopop
a b c popopd ------------------- - c
-rollup popop -
a b c d popopdd ---------------------- - c d
-[popop] dipd -
pop three items from the stack.
a b c popopop -------------------
pop popop
pop popd popdd popop popopd popopdd
Take two numbers a and b from the stack and raise a to the nth power. (b is on the top of the stack.)
a
b
n
Take two numbers a and n from the stack and raise a to the nth power. (n is on the top of the stack.)
a n pow ------------- (aⁿ)
Predecessor. Decrement TOS.
1 -
succ
Simple and useful specialization of the genrec combinator from the original Joy system.
genrec tailrec
Just as sum sums a list of numbers, this function multiplies them together.
1 swap [mul] step
[1] [mul] primrec
+dup bool +
“Quote D” Wrap the second item on the stack in a list.
a b quoted ---------------- [a] b
[unit] dip
This comes from the original Joy stuff.
unit
[0 <=] [1 - dup] anamorphism
If n is less than 1 the resulting list is empty.
range_to_zero
5 range_to_zero --------------------- [0 1 2 3 4 5]
unit [down_to_zero] infra
Note that the order is reversed compared to range.
down_to_zero range
a [b ...] reco -------------------- [a ...]
rest cons
codireco make_generator
[1 2 3 1] 1 remove ------------------------ [2 3 1]
See the “Remove Function” notebook.
[a ...] rest ------------------ [...]
first uncons
[1 2 3] reverse --------------------- [3 2 1]
-<{} shunt +<{} shunt
<{} shunt
a b c rolldown -------------------- b c a
swapd swap
rollup
a b c rollup ------------------- - c a b
-swap swapd -
swap swapd
rolldown
See rollup.
See rolldown.
a b c rollup +------------------ + c a b
+swap swapd +
Round a number to a given precision in decimal digits.
Another one that won’t make sense until the “numeric tower” is nailed down.
[a b ...] rrest --------------------- [...]
rest rest
rest
a n rshift ---------------- (a∕2ⁿ)
lshift
[1 2 +] run ----------------- [3]
-<{} infra +<{} infra
<{} infra
[a b ...] second ---------------------- b
rest first
first third fourth
The sequence can contain more than two items but not fewer.
choice
Print redistribution information.
Mathematically this is a form of id, but it has the side-effect of printing out the GPL notice.
warranty
[x y z] [a b c] shift --------------------------- [a x y z] [b c]
uncons [swons] dip
shunt
[a b c] [d e f] shunt --------------------------- [f e d a b c]
[swons] step
This is more efficient than concat so prefer it if you don’t need to preserve order.
concat reverse shift
[23 [cats] 4] size ------------------------ 3
[pop ++] step_zero
Given a list return it sorted.
Example code.
See the “Square Spiral Example Joy Code” notebook.
[1 2 3 4 5 6 7] 4 split_at -------------------------------- [5 6 7] [4 3 2 1]
[drop] [take] clop
Take a list and a number n from the stack, take n items from the top of the list and shunt them onto a new list that replaces the number n on the top of the stack.
split_list
[1 2 3 4 5 6 7] 4 split_list ---------------------------------- [1 2 3 4] [5 6 7]
[take reverse] [drop] clop
Compare with split_at. This function does extra work to ensure that concat would reconstruct the original list.
split_at
n sqr ------------ n²
dup mul
Basis Function Combinator
Return the square root of the number a. Negative numbers return complex roots.
Another “numeric tower” hatch…
Grab the stack under the top item and put it onto the stack.
... 1 2 3 stackd +------------------------ + ... 1 2 [2 1 ...] 3
+[stack] dip +
[stack] dip
Put the stack onto the stack.
[] swaack dup swaack first
This function forms a pair with [unstack], and together they form the complement to the “destructive” pair enstacken and disenstacken.
[unstack] enstacken disenstacken
... 1 2 3 stackd ------------------------- - ... 1 2 [2 1 ...] 3
-[stack] dip -
Run a quoted program on each item in a sequence.
step_zero
[...] [F] step_zero ------------------------- 0 [...] [F] step
0 roll> step
size and sum can both be defined in terms of this specialization of step.
step
1 2 3 stuncons -------------------- 1 2 3 3 [2 1]
stack uncons
1 2 3 stununcons ---------------------- 1 2 3 3 2 [1]
stack uncons uncons
stuncons
a b sub ------------- (a-b)
add
Successor. Increment TOS.
1 +
pred
[1 2 3 4 5] sum --------------------- 15
[+] step_zero
size
1 2 3 [4 5 6] swaack -------------------------- 6 5 4 [3 2 1]
This function works as a kind of “context switch”. It’s used in the definition of infra.
Swap the second and third items on the stack.
a b c swapd +----------------- + b a c
+[swap] dip +
[swap] dip
over tuck
Swap the top two items on the stack.
swapd
a b c swapd ------------------ - b a c
-[swap] dip -
concat two lists, but swap the lists first.
swap concat
concat
[...] a swons ------------------- [a ...]
swap cons
A specialization of the genrec combinator.
[i] genrec
Some recursive functions do not need to store additional data or pending actions per-call. These are called “tail recursive” functions. In Joy, they appear as genrec definitions that have i for the second half of their recursive branch.
[a b c d] 2 take ---------------------- [b a]
-<<{} [shift] times pop +<<{} [shift] times pop
<<{} [shift] times pop
... z y x [P] ternary ------------------------- ... a
binary popd
Runs any other quoted function and returns its first result while consuming exactly three items from the stack.
binary nullary unary
[a b c ...] third ----------------------- c
rest second
first second fourth rest
[-- dip] cons [swap] infra [0 >] swap while pop :
This works by building a little while program and running it:
1 3 [++] • [-- dip] cons [swap] infra [0 >] swap while pop 1 3 [++] [-- dip] • cons [swap] infra [0 >] swap while pop @@ -2367,11 +2220,11 @@ a F a
a b tuck -------------- b a b
dup [swap] dip
over
... x [P] unary --------------------- ... a
Runs any other quoted function and returns its first result while consuming exactly one item from the stack.
binary nullary ternary
[a ...] uncons -------------------- a [...]
This is the inverse of cons.
cons
a unit ------------ [a]
[] cons
1 2 [3 4] 5 unquoted -------------------------- 1 2 3 4 5
[i] dip
[a ...] unswons --------------------- [...] a
uncons swap
+nulco [nullary] dip [true] branch +
[A] [B] || +---------------- A -> false + B + + + [A] [B] || +---------------- A -> true + true
True if the form on TOS is void otherwise False.