Now then, we have two non-empty lists:
[a b c ...] [e f g ...] R0 [zip] R1
Let's imagine a function shift-pair:
[a ...] [e ...] shift-pair
+Let's imagine a function uncons-pair:
+ [a ...] [e ...] uncons-pair
--------------------------------
[a e] [...] [...]
I'm going to defer derivation of that for now.
-[a b c ...] [e f g ...] shift-pair [zip] R1
+[a b c ...] [e f g ...] uncons-pair [zip] R1
[a e] [b c ...] [f g ...] [zip] R1
And so R1 is i cons (it's a list builder.)
-zip == [null] [pop] [shift-pair] [i cons] genrec
+zip == [null] [pop] [uncons-pair] [i cons] genrec
And now:
-shift-pair == uncons-two [quote-two] dipd
+uncons-pair == uncons-two [quote-two] dipd
w/
uncons-two == [uncons] ii swapd
quote-two == unit cons
-[zip [null] [pop] [shift-pair] [i cons] genrec] inscribe
-[shift-pair uncons-two [quote-two] dipd] inscribe
+[zip [null] [pop] [uncons-pair] [i cons] genrec] inscribe
+[uncons-pair uncons-two [quote-two] dipd] inscribe
[uncons-two [uncons] ii swapd] inscribe
[quote-two unit cons] inscribe
diff --git a/docs/reference/FuncRef.html b/docs/reference/FuncRef.html
index 0fa7d42..5ab1081 100644
--- a/docs/reference/FuncRef.html
+++ b/docs/reference/FuncRef.html
@@ -22,6 +22,9 @@
@@ -214,6 +210,17 @@
Version -10.0.0
Each function, combinator, or definition should be documented here.
+/
+
+Binary Boolean and.
+Crosslinks
+
+
+/
+Binary Boolean or.
+Crosslinks
+
+
abs
Take an integer from the stack and replace it with its absolute value.
@@ -233,7 +240,7 @@
----------------- A -> false
false
TODO: this is derived in one of the notebooks I think, look it up and link to it, or copy the content here.
-Crosslinks
+Crosslinks
anamorphism
@@ -265,7 +272,7 @@
This is the same effect as the unary combinator.
Discussion
Just a specialization of nullary really. Its parallelizable cousins are more useful.
-Crosslinks
+Crosslinks
app2
@@ -278,7 +285,7 @@
Discussion
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.
-Crosslinks
+Crosslinks
app3
@@ -291,7 +298,7 @@
[x ...] [Q] infra first
Discussion
See app2.
-Crosslinks
+Crosslinks
appN
@@ -306,10 +313,10 @@
[x0 ...] [Q] infra first
Discussion
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.
-Crosslinks
+Crosslinks
-*
+*
See mul.
at
@@ -329,7 +336,7 @@
... aRuns any other quoted function and returns its first result while consuming exactly two items from the stack.
-This combinator may seem trivial but it comes in handy.
-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.
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.
-Do cons four times.
-Do cons two times.
-It’s a matter of taste whether you implement this in terms of branch or the other way around.
-See xor.
-Clear everything from the stack.
-One of a handful of useful parallel combinators.
- 1 2 3 4 [+] [-] clop
--------------------------
1 2 7 -1This 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.:
+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 cmpThis is one of those weirdly specific functions that turns out to be useful in a few places.
-This is part of the make_generator function. You would not use this combinator directly.
See make_generator and the “Using x to Generate Values” notebook as well as Recursion Theory and Joy by Manfred von Thun.
[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
[[[B0] T0] [[B1] T1] [D]] cond
-----------------------------------------
[B0] [T0] [[B1] [T1] [D] ifte] ifteCons is a venerable old function from Lisp. Its inverse operation is uncons.
-Combinator
Specialist function (that means I forgot what it does and why.)
Combinator
+Like dip but expects four items. :
+ ... z y x w [Q] . dipddd
+-------------------------------
+ ... . Q z y x wSee dip.
+dip dipd dipdd dupdip dupdipd infra
+Combinator
Like dip but expects three items. :
- ... z y x [Q] . dip
+ ... z y x [Q] . dipdd
-----------------------------
... . Q z y x
-Discussion
+Discussion
See dip.
-Crosslinks
-
+Crosslinks
+dip dipd dipddd dupdip dupdipd infra
dipd
Combinator
@@ -535,10 +550,10 @@ cond ... y x [Q] . dipd
-------------------------
... . Q y xSee dip.
-dip dipdd dupdip dupdipd infra
+dip dipdd dipddd dupdip dupdipd infra
Combinator
@@ -546,10 +561,10 @@ cond ... x [Q] . dip
---------------------
... . Q xThis 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.)
dipd dipdd dupdip dupdipd infra
1 2 3 [4 5 6] disenstacken
--------------------------------
6 5 4Note 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.
-See floordiv.
+Divide.
x y divmod
@@ -578,7 +593,7 @@ cond 3 down_to_zero
--------------------
3 2 1 0 [a b c d] 2 drop
----------------------
[c d] a b c dupdd
-----------------
a a b c a [F] dupdipd
-------------------
F a [F]A very common and useful combinator.
- a b dupd
--------------
a a b a dup
-----------
a a ... a b c enstacken
-------------------------
[c b a ...]This is a destructive version of stack. See the note under disenstacken about the apparent but illusory reversal of the stack.
-Compare the two items on the top of the stack for equality and replace them with a Boolean value.
@@ -657,16 +672,16 @@ a F a ------------- Boolean (a = b) -See eq.
See ne.
+See neq.
Not negative.
n !-
----------- n < 0
@@ -676,7 +691,7 @@ a F aReturn a Boolean value indicating if a number is greater than or equal to zero.
[a ...]
--------------
a [a b ...] first_two
-------------------------
a bfirst second third fourth rest
[[1 2] [3 [4] 5] [6 7]] flatten
-------------------------------------
[1 2 3 [4] 5 6 7]Note that only one “level” of lists is flattened. In the example above [4] is not unquoted.
concat first first_two fourth getitem remove rest reverse rrest second shift shunt size sort split_at split_list swaack third zip
-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.
-Return the largest integer <= x.
-This function doesn’t make sense (yet) to have because there are (as yet) only integers in the system.
+Note that only one “level” of lists is flattened. In the example above [4] is not unquoted.
concat first first_two fourth getitem remove rest reverse rrest second shift shunt size sort split_at split_list swaack third zip
Combinator
@@ -727,9 +727,9 @@ a F a ... [F] [G] fork
----------------------
... f gThe basic parallelism combinator, the two programs are run independently.
- [a b c d ...] fourth
--------------------------
dCompiled GCD function.
-See gcd.
-Take two integers from the stack and replace them with their Greatest Common Denominator.
-Euclid’s Algorithm
Combinator
@@ -767,7 +760,7 @@ a F a [if] [then] [rec1] [rec2] genrec
---------------------------------------------------------------------
[if] [then] [rec1 [[if] [then] [rec1] [rec2] genrec] rec2] ifteNote 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.
See the Recursion Combinators notebook.
From “Recursion Theory and Joy” by Manfred von Thun:
@@ -786,7 +779,7 @@ a F aP == [I] [T] [R] tailrec
== [I] [T] [R [P] i] ifte
== [I] [T] [R P] ifte [a b c d] 2 getitem
-------------------------
cIf 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.)
concat first first_two flatten fourth remove rest reverse rrest second shift shunt size sort split_at split_list swaack third zip
It grabs the stack under the top item, and substitutes it for the second item down on the stack.
-This function “grabs” an item from the stack along with a copy of the stack. It’s part of the app2 definition.
-See ge.
See rshift.
See gt.
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.
See pred.
See sub.
x y hypot
----------------------------
- sqrt(sqr(x) + sqr(y))This is another function that has to wait on the numeric tower.
-The identity function.
-Does nothing. It’s kind of a mathematical thing, but it occasionally comes in handy.
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
--------------------
@@ -907,7 +891,7 @@ a F a [Q] . i
-------------
. QThis is a fundamental combinator. It is used in all kinds of places. For example, the x combinator can be defined as dup i.
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.
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] inscribeThis 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.
See le.
See ne.
+See neq.
... a <{}
----------------
... [] aTuck an empty list just under the first item on the stack.
... b a <{}
-----------------
... [] b aTuck an empty list just under the first two items on the stack.
See lshift.
See lt.
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.
@@ -1015,7 +999,7 @@ d e [...] swaack Boolean (a < b)Crosslinks
- +
make_generator
Given an initial state value and a quoted generator function build a generator quote.
@@ -1030,7 +1014,7 @@ d e [...] swaack-[230 [dup ++] codireco] 5 [x] times pop --------------------------------------------- 230 231 232 233 234Discussion
+Discussion
See the “Using
xto Generate Values” notebook.Crosslinks
@@ -1042,7 +1026,7 @@ d e [...] swaack-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
@@ -1090,9 +1074,9 @@ d e [...] swaack ----------- -a
-ne
+neq
Not-Equal comparison of the two items on the top of the stack, replacing them with a Boolean value.
-a b ne +@@ -1100,7 +1084,7 @@ d e [...] swaacka b neq ------------- Boolean (a = b)
not
-Like bool but convert the item on the top of the stack to the inverse Boolean value.
+Invert the Boolean value on the top of the stack.
-true not -------------- false @@ -1116,11 +1100,14 @@ d e [...] swaack-[F] nulco ------------------- [[F] nullary]Discussion
+Discussion
Helper function for or and and.
Crosslinks
+null
+True if the item on the top of the stack is an empty list, false if it’s a list but not empty, and an error if it’s not a list.
+
nullary
Combinator
Run a quoted program without using any stack values and leave the first item of the result on the stack.
@@ -1134,7 +1121,7 @@ d e [...] swaack ... [...] [P] infra first ... [a ...] first ... aDiscussion
+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
@@ -1151,7 +1138,7 @@ d e [...] swaackor
Logical bit-wise OR.
Crosslinks
- +
over
dup the second item on the stack
@@ -1176,7 +1163,7 @@ d e [...] swaackoverthe first.
And so on…
-A fine old word from Forth.
5 7 [[+][-][*][/][%]] pam
-------------------------------
5 7 [12 -2 35 0 5]A specialization of map that runs a list of functions in parallel (if the underlying map function is so implemented, of course.)
See mod.
See getitem.
See add.
See succ.
Simple and useful specialization of the genrec combinator from the original Joy system.
Is the item on the top of the stack “truthy”?
-You often want to test the truth value of an item on the stack without consuming the item.
a b quoted
----------------
[a] bThis comes from the original Joy stuff.
If n is less than 1 the resulting list is empty.
5 range_to_zero
---------------------
[0 1 2 3 4 5]Note that the order is reversed compared to range.
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
---------------------
@@ -1455,14 +1437,14 @@ d e [...] swaack
[a b] true select
-----------------------
bThe sequence can contain more than two items but not fewer.
Print redistribution information.
-Mathematically this is a form of id, but it has the side-effect of printing out the GPL notice.
[a b c] [d e f] shunt
---------------------------
[f e d a b c] This is more efficient than concat so prefer it if you don’t need to preserve order.
See floordiv.
+See div.
See floordiv.
-See floordiv.
+Return true if the item on the top of the stack is a list with zero or one item in it, false if it is a list with more than one item in it, and an error if it is not a list.
Given a list return it sorted.
@@ -1512,7 +1493,7 @@ d e [...] swaackExample 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]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.
[1 2 3 4 5 6 7] 4 split_list
----------------------------------
[1 2 3 4] [5 6 7]Compare with split_at. This function does extra work to ensure that concat would reconstruct the original list.
-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 ...] 3Put the stack onto the stack.
... c b a stack
---------------------------
... c b a [a b c ...]This function forms a pair with [unstack], and together they form the complement to the “destructive” pair enstacken and disenstacken.
-This function forms a pair with unstack, and together they form the complement to the “destructive” pair enstacken and disenstacken.
+enstacken disenstacken stackd unstack
Combinator
@@ -1581,9 +1558,9 @@ d e [...] swaack ... [a b c] [Q] . step ---------------------------------------- ... a . Q [b c] [Q] step -See the Recursion Combinators notebook.
- [...] [F] step_zero
-------------------------
0 [...] [F] stepsize and sum can both be defined in terms of this specialization of step.
- 1 2 3 stununcons
----------------------
1 2 3 3 2 [1] a b sub
-------------
(a-b)Successor. Increment TOS.
- [1 2 3 4 5] sum
---------------------
15 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.
- a b c swapd
-----------------
b a c a b swap
--------------
b aconcat two lists, but swap the lists first.
-Combinator
A specialization of the genrec combinator.
-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.
See the Recursion Combinators notebook.
- ... z y x [P] ternary
-------------------------
... aRuns any other quoted function and returns its first result while consuming exactly three items from the stack.
- [a b c ...] third
-----------------------
cThis 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
@@ -1735,15 +1712,12 @@ d e [...] swaack
1 3 [0 >] [-- [++] dip] • while popThis is a common pattern in Joy. You accept some parameters from the stack which typically include qouted programs and use them to build another program which does the actual work. This is kind of like macros in Lisp, or preprocessor directives in C.
See bool.
-dup the item on the top of the stack under the second item on the stack.
a b tuck
--------------
b a b ... x [P] unary
---------------------
... aRuns any other quoted function and returns its first result while consuming exactly one item from the stack.
- [a ...] uncons
--------------------
a [...]This is the inverse of cons.
-Take a list from the top of the stack and concat it to the stack.
joy? 1 2 3 [4 5 6]
+
+1 2 3 [4 5 6]
+
+joy? unstack
+
+1 2 3 6 5 4Combinator
Unquote (using i) the list that is second on the stack.
@@ -1782,7 +1768,7 @@ d e [...] swaack 1 2 [3 4] 5 unquoted
--------------------------
1 2 3 4 5Combinator
Short-circuiting Boolean OR
-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
@@ -1803,12 +1789,12 @@ d e [...] swaack
[A] [B] ||
---------------- A -> true
trueTrue if the form on TOS is void otherwise False.
-A form is any Joy expression composed solely of lists. This represents a binary Boolean logical formula in the arithmetic of the “Laws of Form”, see The Markable Mark
Print all the words in alphabetical order.
-Mathematically this is a form of id.
- [F] x
-----------
[F] FThe simplest recursive pattern.
See the Recursion Combinators notebook. as well as Recursion Theory and Joy by Manfred von
Logical bit-wise eXclusive OR.
-Replace the two lists on the top of the stack with a list of the pairs from each list. The smallest list sets the length of the result list.
[1 2 3] [4 5 6] zip
-------------------------
- [[4 1] [5 2] [6 3]]