From 86613734351850bc9be8427f7555545d8b5fb28d Mon Sep 17 00:00:00 2001 From: sforman Date: Sun, 1 Oct 2023 09:21:16 -0700 Subject: [PATCH] A little more work on the ref doc. --- docs/html/FuncRef.html | 2285 +++----------------------- docs/html/css/func_ref.css | 9 +- docs/reference/Function-Reference.md | 666 +------- docs/reference/to_html.py | 142 +- 4 files changed, 398 insertions(+), 2704 deletions(-) diff --git a/docs/html/FuncRef.html b/docs/html/FuncRef.html index 7422c66..e1f0a3b 100644 --- a/docs/html/FuncRef.html +++ b/docs/html/FuncRef.html @@ -1,8 +1,6 @@ -Thun Function Reference

Thun Function Reference

Home

Version -10.0.0

Each function, combinator, or definition should be documented here.

!- 

+Thun Function Reference
Thun Function Reference
Home
Version -10.0.0
Each function, combinator, or definition should be documented here.
!- 
 
 
-Function
-
 Not negative.
 
 
@@ -15,32 +13,23 @@ Not negative.
     ---------- n >= 0
        true
 
-
-### Definition
-
-    0 \>=
-
-### Discussion
-
-Return a Boolean value indicating if a number is greater than or equal to
-zero.
-
-
!= 
+
Definition
0 >=
Discussion
Return a Boolean value indicating if a number is greater than or equal to
+zero.
Used By
spiral_next
!= 
 
 
 See [ne](#ne).
 
-
% 
+
% 
 
 
 See [mod](#mod).
 
-
& 
+
Used By
divmod mod
& 
 
 
 See [and](#and).
 
-
&& 
combinator
+
&& 
combinator
 
 
 
@@ -70,186 +59,122 @@ stack.)
 
 TODO: this is derived in one of the notebooks I think, look it up and
 link to it, or copy the content here.
-
-### Discussion
-
-This is seldom useful, I suspect, but this way you have it.
-
-### Crosslinks
-
-[||](#section-25)
-
-
* 
+
Discussion
This is seldom useful, I suspect, but this way you have it.
See Also
||
* 
 
 
 See [mul](#mul).
 
-
+ 
+
Used By
lshift pow product
+ 
 
 
 See [add](#add).
 
-
++ 
+
Used By
++ hypot pm sum
++ 
 
 
 See [succ](#succ).
 
-
- 
+
Definition
1 +
Used By
size spiral_next
- 
 
 
 See [sub](#sub).
 
-
-- 
+
Used By
-- neg pm
-- 
 
 
 See [pred](#pred).
 
-
/ 
+
Definition
1 -
Used By
down_to_zero range spiral_next
/ 
 
 
 See [floordiv](#floordiv).
 
-
// 
+
Used By
average divmod rshift
// 
 
 
 See [floordiv](#floordiv).
 
-
/floor 
+
/floor 
 
 
 See [floordiv](#floordiv).
 
-
< 
+
< 
 
 
 See [lt](#lt).
 
-
<< 
+
Used By
abs
<< 
 
 
 See [lshift](#lshift).
 
-
<<{} 
+
Definition
lshift
<<{} 
 
 
-Function
-
 
        ... b a <{}
     -----------------
        ... [] b a
 
-
-### Definition
-
-    [] rollup
-
-
-### Discussion
-
-Tuck an empty list just under the first two items on the stack.
-
-### Crosslinks
-
-[<{}](#section-16)
-
-
<= 
+
Definition
[] rollup
Discussion
Tuck an empty list just under the first two items on the stack.
See Also
<{}
Used By
take
<= 
 
 
 See [le](#le).
 
-
<> 
+
Used By
range spiral_next
<> 
 
 
 See [ne](#ne).
 
-
<{} 
+
Used By
spiral_next
<{} 
 
 
-Function
-
 
        ... a <{}
     ----------------
        ... [] a
 
-
-### Definition
-
-    [] swap
-
-### Discussion
-
-Tuck an empty list just under the first item on the stack.
-
-### Crosslinks
-
-[<<{}](#section-18)
-
-
= 
+
Definition
[] swap
Discussion
Tuck an empty list just under the first item on the stack.
See Also
<<{}
Used By
flatten grabN reverse run
= 
 
 
 See [eq](#eq).
 
-
> 
+
Used By
cmp
> 
 
 
 See [gt](#gt).
 
-
>= 
+
Used By
cmp down_to_zero gcd
>= 
 
 
 See [ge](#ge).
 
-
>> 
+
Used By
!-
>> 
 
 
 See [rshift](#rshift).
 
-
? 
+
Definition
rshift
? 
 
 
-Function
-
 Is the item on the top of the stack "truthy"?
-
-### Definition
-
-> [dup](#dup) [bool](#bool)
-
-### Discussion
-
-You often want to test the truth value of an item on the stack without
-consuming the item.
-
-### Crosslinks
-
-[bool](#bool)
-
-
^ 
+
Definition
dup bool
Discussion
You often want to test the truth value of an item on the stack without
+consuming the item.
See Also
bool
^ 
 
 
 See [xor](#xor).
 
-
abs 
+
abs 
 
 
-Function
-
 Return the absolute value of the argument.
+
Definition
dup 0 < [] [neg] branch
Used By
spiral_next
add 
 
-### Definition
-
-> [dup](#dup) 0 < [] \[[neg](#neg)\] [branch](#branch)
-
-
add 
-
-
-Function
 
 Add two numbers together: a + b.
 
-
anamorphism 
combinator
+
anamorphism 
combinator
 
 
 
@@ -260,33 +185,16 @@ predicate `P`.
     -----------------------------------------
        [P] [pop []] [G] [dip swons] genrec
 
-### Definition
-
-> \[[pop](#pop) \[\]\] [swap](#swap) \[[dip](#dip) [swons](#swons)\] [genrec](#genrec)
-
 ### Example
 
 The `range` function generates a list of the integers from 0 to n - 1:
 
 > \[0 <=\] \[\-\- dup\] anamorphism
+
Definition
[pop []] swap [dip swons] genrec
Discussion
See the [Recursion Combinators notebook](https://joypy.osdn.io/notebooks/Recursion_Combinators.html).
Used By
range
and 
 
-### Discussion
-
-See the [Recursion Combinators notebook](https://joypy.osdn.io/notebooks/Recursion_Combinators.html).
-
-
and 
-
-
-Function
 
 Logical bit-wise AND.
-
-### Crosslinks
-
-[or](#or)
-[xor](#xor)
-
-
app1 
combinator
+
Definition
nulco [nullary [false]] dip branch
See Also
or xor
Used By
spiral_next
app1 
combinator
 
 
 "apply one"
@@ -301,24 +209,8 @@ the first result of the program.
        ... [x ...] [Q] infra first
 
 This is the same effect as the [unary](#unary) combinator.
-
-### Definition
-
-> [nullary](#nullary) [popd](#popd)
-
-### Discussion
-
-Just a specialization of `nullary` really.  Its parallelizable cousins
-are more useful.
-
-### Crosslinks
-
-[app2](#app2)
-[app3](#app3)
-[appN](#appN)
-[unary](#unary)
-
-
app2 
combinator
+
Definition
grba infrst
Discussion
Just a specialization of `nullary` really.  Its parallelizable cousins
+are more useful.
See Also
app2 app3 appN unary
app2 
combinator
 
 
 
@@ -329,30 +221,14 @@ Like [app1](#app1) with two items.
        ... [y ...] [Q] . infra first
            [x ...] [Q]   infra first
 
-### Definition
-
-> \[[grba] [swap] [grba] [swap]\] [dip] \[[infrst]\] [cons] [ii]
-
-### Discussion
-
-Unlike [app1](#app1), which is essentially an alias for [unary](#unary),
+
Definition
[grba swap grba swap] dip [infrst] cons ii
Discussion
Unlike [app1](#app1), which is essentially an alias for [unary](#unary),
 this function is not the same as [binary](#binary).  Instead of running
 one program using exactly two items from the stack and pushing one
 result (as [binary](#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
-
-[app1](#app1)
-[app3](#app3)
-[appN](#appN)
-[unary](#unary)
-
-

app3

combinator

+should) be done.

See Also

app1 app3 appN unary

Used By

fork

app3

combinator

 
 
 
@@ -363,23 +239,7 @@ Like [app1] with three items.
        ... [z ...] [Q] . infra first
            [y ...] [Q]   infra first
            [x ...] [Q]   infra first
-
-### Definition
-
-> 3 [appN]
-
-### Discussion
-
-See [app2].
-
-### Crosslinks
-
-[app1](#app1)
-[app2](#app2)
-[appN](#appN)
-[unary](#unary)
-
-

appN

combinator

+

Definition

3 appN

Discussion

See [app2].

See Also

app1 app2 appN unary

appN

combinator

 
 
 
@@ -392,52 +252,24 @@ Like [app1] with any number of items.
            [x2 ...] [Q]   infra first
            [x1 ...] [Q]   infra first
            [x0 ...] [Q]   infra first
-
-### Definition
-
-> \[[grabN]\] [codi] [map] [disenstacken]
-
-### 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
-
-[app1](#app1)
-[app2](#app2)
-[app3](#app3)
-[unary](#unary)
-
-

at 

+

Definition

[grabN] codi map reverse disenstacken

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].

See Also

app1 app2 app3 unary

Used By

app3

at 

 
 
 See [getitem](#getitem).
 
-

average 

+

Definition

drop first

Used By

of

average 

 
 
-Function
-
 Compute the average of a list of numbers.
 (Currently broken until I can figure out what to do about "numeric tower"
 in Thun.)
-
-### Definition
-
-> \[[sum]\] \[[size]\] [cleave] [/]
-
-### Discussion
-
-Theoretically this function would compute the sum and the size in two
+

Definition

[sum] [size] cleave /

Discussion

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](https://joypy.osdn.io/notebooks/Recursion_Combinators.html). - -

b

combinator

+See the [Recursion Combinators notebook](https://joypy.osdn.io/notebooks/Recursion_Combinators.html).

b

combinator

 
 
 
@@ -446,21 +278,7 @@ Run two quoted programs
        [P] [Q] b
     ---------------
           P Q
-
-### Definition
-
-> \[[i]\] [dip] [i]
-
-### Discussion
-
-This combinator may seem trivial but it comes in handy.
-
-### Crosslinks
-
-[dupdip](#dupdip)
-[ii](#ii)
-
-

binary

combinator

+

Definition

[i] dip i

Discussion

This combinator may seem trivial but it comes in handy.

See Also

dupdip ii

binary

combinator

 
 
 
@@ -470,39 +288,13 @@ item of the result on the stack.
        ... y x [P] binary
     -----------------------
             ... a
+

Definition

unary popd

Discussion

Runs any other quoted function and returns its first result while +consuming exactly two items from the stack.

See Also

nullary ternary unary

Used By

ternary

bool 

 
-### Definition
-
-> [unary] [popd]
-
-### Discussion
-
-Runs any other quoted function and returns its first result while
-consuming exactly two items from the stack.
-
-### Crosslinks
-
-[nullary](#nullary)
-[ternary](#ternary)
-[unary](#unary)
-
-

bool 

-
-
-Function
 
 Convert the item on the top of the stack to a Boolean value.
-
-### Discussion
-
-For integers 0 is `false` and any other number is `true`; for lists the
-empty list is `false` and all other lists are `true`.
-
-### Crosslinks
-
-[not]
-
-

branch

combinator

+

Discussion

For integers 0 is `false` and any other number is `true`; for lists the +empty list is `false` and all other lists are `true`.

See Also

not

Used By

? null

branch

combinator

 
 
 
@@ -517,66 +309,26 @@ Use a Boolean value to select and run one of two quoted programs.
     -------------------------
                  T
 
-
-### Definition
-
-> [rolldown] [choice] [i]
-
-### Discussion
-
-This is one of the fundamental operations (although it can be defined in
+

Discussion

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]. +[ifte] adds a predicate function that is evaluated [nullary].

See Also

choice ifte select

Used By

/\ \/ abs and ifte not or small xor

ccccons 

 
-### Crosslinks
-
-[choice]
-[ifte]
-[select]
-
-

ccccons 

-
-
-Function
 
        a b c d [...] ccccons
     ---------------------------
            [a b c d ...]
 
 Do [cons] four times.
+

Definition

ccons ccons

See Also

ccons cons times

Used By

genrec

ccons 

 
-### Definition
-
-> [ccons] [ccons]
-
-### Crosslinks
-
-[ccons] [cons] [times]
-
-

ccons 

-
-
-Function
 
        a b [...] ccons
     ---------------------
           [a b ...]
 
 Do [cons] two times.
+

Definition

cons cons

See Also

cons ccons

Used By

ccccons cmp make_generator

choice 

 
-### Definition
-
-> [cons] [cons]
-
-### Crosslinks
-
-[cons]
-[ccons]
-
-

choice 

-
-
-Function
 
 Use a Boolean value to select one of two items.
 
@@ -587,38 +339,12 @@ Use a Boolean value to select one of two items.
        a b true choice
     ---------------------
               b
+

Discussion

It's a matter of taste whether you implement this in terms of [branch] or +the other way around.

See Also

branch select

clear 

 
-### Definition
-
-> \[[pop]\] \[[popd]\] [branch]
-
-### Discussion
-
-It's a matter of taste whether you implement this in terms of [branch] or
-the other way around.
-
-### Crosslinks
-
-[branch]
-[select]
-
-

clear 

-
-
-Function
 
 Clear everything from the stack.
-
-### Definition
-
-> [stack] [bool] \[[pop] [stack] [bool]\] [loop]
-
-### Crosslinks
-
-[stack]
-[swaack]
-
-

cleave

combinator

+

Definition

[] swaack pop

See Also

stack swaack

Used By

enstacken

cleave

combinator

 
 
 
@@ -638,18 +364,7 @@ results on the stack.
        1 2 3 [+] [-] cleave
     --------------------------
              1 2 5 -1
-
-### Discussion
-
-One of a handful of useful parallel combinators.
-
-### Crosslinks
-
-[clop]
-[fork]
-[map]
-
-

clop

combinator

+

Definition

fork popdd

Discussion

One of a handful of useful parallel combinators.

See Also

clop fork map

Used By

average clop

clop

combinator

 
 
 
@@ -658,26 +373,10 @@ Run two programs in parallel, consuming two additional items, and put their resu
        ... x y [A] [B] clop
     --------------------------
             ... a b
-
-### Definition
-
-> [cleave] [popdd]
-
-### Discussion
-
-Like [cleave] but consumes an additional item from the stack.
-
+

Definition

cleave popdd

Discussion

Like [cleave] but consumes an additional item from the stack. 1 2 3 4 [+] [-] clop -------------------------- - 1 2 7 -1 - -### Crosslinks - -[cleave] -[fork] -[map] - -

cmp

combinator

+             1 2 7 -1

See Also

cleave fork map

Used By

divmod pm split_at split_list

cmp

combinator

 
 
 
@@ -694,26 +393,13 @@ of the three depending on the results of comparing the two values.
 
        a b [G] [E] [L] cmp
     ------------------------- a < b
-                    L
-### Discussion
-
-This is useful sometimes, and you can [dup] or [dupd] with two quoted
+                    L

Definition

[[>] swap] dipd [ifte] ccons [=] swons ifte

Discussion

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 - -### Crosslinks - -TODO: link to tree notebooks where this was used. - -

codi

combinator

+    [GL] [E] over cmp

Used By

eq ge gt le lt neq

codi

combinator

 
 
 
@@ -723,77 +409,25 @@ Take a quoted program from the stack, [cons] the next item onto it, then
        a b [F] . codi
     --------------------
              b . F a
-
-### Definition
-
-> [cons] [dip]
-
-### Discussion
-
-This is one of those weirdly specific functions that turns out to be
-useful in a few places.
-
-### Crosslinks
-
-[appN]
-[codireco]
-
-

codireco

combinator

+

Definition

cons dip

Discussion

This is one of those weirdly specific functions that turns out to be +useful in a few places.

See Also

appN codireco

Used By

appN codireco dipd

codireco

combinator

 
 
 
 This is part of the [make_generator] function.  You would not use this
 combinator directly.
-
-### Definition
-
-> [codi] [reco]
-
-### Discussion
-
-See [make_generator] and the 
+

Definition

codi reco

Discussion

See [make_generator] and the ["Using `x` to Generate Values" notebook](https://joypy.osdn.io/notebooks/Generator_Programs.html#an-interesting-variation) as well as -[Recursion Theory and Joy](https://www.kevinalbrecht.com/code/joy-mirror/j05cmp.html) by Manfred von Thun. +[Recursion Theory and Joy](https://www.kevinalbrecht.com/code/joy-mirror/j05cmp.html) by Manfred von Thun.

See Also

make_generator

Used By

make_generator

concat 

 
-### Crosslinks
-
-[make_generator]
-
-

concat 

-
-
-Function
 
 Concatinate two lists.
 
        [a b c] [d e f] concat
     ----------------------------
            [a b c d e f]
-
-### Crosslinks
-
-[first]
-[first_two]
-[flatten]
-[fourth]
-[getitem]
-[remove]
-[rest]
-[reverse]
-[rrest]
-[second]
-[shift]
-[shunt]
-[size]
-[sort]
-[split_at]
-[split_list]
-[swaack]
-[third]
-[zip]
-
-

cond

combinator

+

See Also

first first_two flatten fourth getitem remove rest reverse rrest second shift shunt size sort split_at split_list swaack third zip

Used By

flatten genrec null swoncat while

cond

combinator

 
 
 
@@ -811,52 +445,25 @@ followed by the function expression to run if that predicate returns
         [Default]
     ]
     cond
-
-### Discussion
-
-It works by rewriting into a chain of nested [ifte]{.title-ref}
+

Discussion

It works by rewriting into a chain of nested [ifte]{.title-ref} expressions, e.g.: - [[[B0] T0] [[B1] T1] [D]] cond ----------------------------------------- - [B0] [T0] [[B1] [T1] [D] ifte] ifte + [B0] [T0] [[B1] [T1] [D] ifte] ifte

See Also

ifte

cons 

 
 
-### Crosslinks
-
-[ifte]
-
-

cons 

-
-
-Function
-
 Given an item and a list, append the item to the list to make a new list.
 
        a [...] cons
     ------------------
          [a ...]
-
-### Discussion
-
-Cons is a [venerable old function from Lisp](https://en.wikipedia.org/wiki/Cons#Lists).
-Its inverse operation is [uncons].
-
-### Crosslinks
-
-[uncons]
-
-

dinfrirst

combinator

+

Discussion

Cons is a [venerable old function from Lisp](https://en.wikipedia.org/wiki/Cons#Lists). +Its inverse operation is [uncons].

See Also

uncons

Used By

app2 ccons codi grabN map nulco pow reco swons unit

dinfrirst

combinator

 
 
 
 Specialist function (that means I forgot what it does and why.)
-
-### Definition
-
-> [dip] [infrst]
-
-

dip

combinator

+

Definition

dip infrst

Used By

nullary

dip

combinator

 
 
 
@@ -867,12 +474,8 @@ on the rest of the stack.
        ... x [Q] . dip
     ---------------------
              ... . Q x
-
-### Discussion
-
-This along with [infra] are enough to update any datastructure.
+

Discussion

This along with [infra] are enough to update any datastructure. See the ["Traversing Datastructures with Zippers" notebook](https://joypy.osdn.io/notebooks/Zipper.html). - 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 @@ -883,17 +486,7 @@ 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.) - -### Crosslinks - -[dipd] -[dipdd] -[dupdip] -[dupdipd] -[infra] - -

dipd

combinator

+pending expression (not counting modifications to the dictionary.)

See Also

dipd dipdd dupdip dupdipd infra

Used By

anamorphism and app2 b codi dinfrirst dipd dupd dupdip enstacken grba ii infra map or over popd popopd quoted shift spiral_next stackd swapd unquoted unstack

dipd

combinator

 
 
 
@@ -902,19 +495,7 @@ Like [dip] but expects two items.
        ... y x [Q] . dipd
     -------------------------
                ... . Q y x
-
-### Discussion
-
-See [dip].
-
-### Crosslinks
-
-[dip]
-[dipdd]
-[dupdip]
-[dupdipd]
-[infra]
-

dipdd

combinator

+

Definition

[dip] codi

Discussion

See [dip].

See Also

dip dipdd dupdip dupdipd infra

Used By

cmp dupdd dupdipd ifte popdd popopdd

dipdd

combinator

 
 
 
@@ -922,23 +503,8 @@ Like [dip] but expects three items. :
 
        ... z y x [Q] . dip
     -----------------------------
-                 ... . Q z y x
-### Discussion
+                 ... . Q z y x

Discussion

See [dip].

See Also

dip dipd dupdip dupdipd infra

disenstacken 

 
-See [dip].
-
-### Crosslinks
-
-[dip]
-[dipd]
-[dupdip]
-[dupdipd]
-[infra]
-
-

disenstacken 

-
-
-Function
 
 The `disenstacken` function expects a list on top of the stack and makes
 that the stack discarding the rest of the stack.
@@ -946,33 +512,16 @@ that the stack discarding the rest of the stack.
        1 2 3 [4 5 6] disenstacken
     --------------------------------
                 6 5 4
-
-### Definition
-
-> \[[clear]\] [dip] [reverse] [unstack](#unstack)
-
-### Discussion
-
-Note that the order of the list is not changed, it just looks that way
+

Definition

swaack pop

Discussion

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. - -### Crosslinks - -[enstacken] -[stack] -[unstack](#unstack) - -

div 

+printed with the top or head on the left.

See Also

enstacken stack

Used By

appN

div 

 
 
 See [floordiv](#floordiv).
 
-

divmod 

+

divmod 

 
 
-Function
-
         x y divmod
     ------------------
          q      r
@@ -980,15 +529,8 @@ Function
 
 Invariant: `qy + r = x`.
 
+

Definition

[/] [%] clop

down_to_zero 

 
-### Definition
-
-> \[[floordiv]\] \[[mod]\] [clop]
-
-

down_to_zero 

-
-
-Function
 
 Given a number greater than zero put all the Natural numbers (including
 zero) less than that onto the stack.
@@ -998,19 +540,8 @@ zero) less than that onto the stack.
        3 down_to_zero
     --------------------
           3 2 1 0
+

Definition

[0 >] [dup --] while

See Also

range

Used By

range_to_zero

drop 

 
-### Definition
-
-> \[0 \>\] \[[dup] [--]\] [while]
-
-### Crosslinks
-
-[range]
-
-

drop 

-
-
-Function
 
 Expects an integer and a quote on the stack and returns the quote with n
 items removed off the top.
@@ -1020,78 +551,31 @@ items removed off the top.
        [a b c d] 2 drop
     ----------------------
            [c d]
+

Definition

[rest] times

See Also

take

Used By

at split_at split_list

dup 

 
-### Definition
-
-> \[[rest]\] [times]
-
-### Crosslinks
-
-[take]
-
-

dup 

-
-
-Function
 
 "Dup"licate the top item on the stack.
 
        a dup
     -----------
         a a
+

See Also

dupd dupdd dupdip dupdipd

Used By

? abs down_to_zero dupd dupdd dupdipd gcd over range small sqr tuck x

dupd 

 
-### Crosslinks
-
-[dupd]
-[dupdd]
-[dupdip]
-[dupdipd]
-
-

dupd 

-
-
-Function
 
 [dup] the second item down on the stack.
 
        a b dupd
     --------------
         a a b
+

Definition

[dup] dip

See Also

dup dupdd dupdip dupdipd

Used By

dupdip

dupdd 

 
-### Definition
-
-> \[[dup]\] [dip]
-
-### Crosslinks
-
-[dup]
-[dupdd]
-[dupdip]
-[dupdipd]
-
-

dupdd 

-
-
-Function
 
 [dup] the third item down on the stack.
 
        a b c dupdd
     -----------------
          a a b c
-
-### Definition
-
-> \[[dup]\] [dipd]
-
-### Crosslinks
-
-[dup]
-[dupd]
-[dupdip]
-[dupdipd]
-
-

dupdip

combinator

+

Definition

[dup] dipd

See Also

dup dupd dupdip dupdipd

dupdip

combinator

 
 
 
@@ -1101,10 +585,6 @@ Apply a function `F` and [dup] the item under it on the stack.
     ------------------
           a F a
 
-### Definition
-
-> [dupd] [dip]
-
 ### Derivation
 
     a [F] dupdip
@@ -1113,16 +593,7 @@ Apply a function `F` and [dup] the item under it on the stack.
     a dup [F] dip
     a a [F] dip
     a F a
-
-### Discussion
-
-A very common and useful combinator.
-
-### Crosslinks
-
-[dupdipd]
-
-

dupdipd

combinator

+

Definition

dupd dip

Discussion

A very common and useful combinator.

See Also

dupdipd

Used By

ii uncons

dupdipd

combinator

 
 
 
@@ -1131,19 +602,8 @@ Run a copy of program `F` under the next item down on the stack.
        a [F] dupdipd
     -------------------
           F a [F]
+

Definition

dup dipd

See Also

dupdip

Used By

while

enstacken 

 
-### Definition
-
-> [dup] [dipd]
-
-### Crosslinks
-
-[dupdip]
-
-

enstacken 

-
-
-Function
 
 Put the stack onto the stack replacing the contents of the stack.
 
@@ -1151,26 +611,9 @@ Put the stack onto the stack replacing the contents of the stack.
     -------------------------
            [c b a ...]
 
+

Definition

stack [clear] dip

Discussion

This is a destructive version of [stack]. See the note under +[disenstacken] about the apparent but illusory reversal of the stack.

See Also

stack disenstacken

eq 

 
-### Definition
-
-> [stack] \[[clear]\] [dip]
-
-### Discussion
-
-This is a destructive version of [stack].  See the note under
-[disenstacken] about the apparent but illusory reversal of the stack.
-
-### Crosslinks
-
-[stack]
-[unstack]
-[disenstacken]
-
-

eq 

-
-
-Function
 
 Compare the two items on the top of the stack for equality and replace
 them with a Boolean value.
@@ -1179,65 +622,24 @@ them with a Boolean value.
     -------------
        Boolean
        (a = b)
+

Definition

[false] [true] [false] cmp

See Also

cmp ge gt le lt ne

first 

 
-### Crosslinks
-
-[cmp]
-[ge]
-[gt]
-[le]
-[lt]
-[ne]
-
-

first 

-
-
-Function
 
 Replace a list with its first item.
 
        [a ...]
     --------------
           a
+

Definition

uncons pop

See Also

second third fourth rest

Used By

at infrst second uncons

first_two 

 
-### Definition
-
-> [uncons] [pop]
-
-### Crosslinks
-
-[second]
-[third]
-[fourth]
-[rest]
-
-

first_two 

-
-
-Function
 
 Replace a list with its first two items.
 
        [a b ...] first_two
     -------------------------
                a b
+

See Also

first second third fourth rest

flatten 

 
-### Definition
-
-> [uncons] [first]
-
-### Crosslinks
-
-[first]
-[second]
-[third]
-[fourth]
-[rest]
-
-

flatten 

-
-
-Function
 
 Given a list of lists, concatinate them.
 
@@ -1246,54 +648,14 @@ Given a list of lists, concatinate them.
        [[1 2] [3 [4] 5] [6 7]] flatten
     -------------------------------------
               [1 2 3 [4] 5 6 7]
+

Definition

<{} [concat] step

Discussion

Note that only one "level" of lists is flattened. In the example above +`[4]` is not unquoted.

See Also

concat first first_two fourth getitem remove rest reverse rrest second shift shunt size sort split_at split_list swaack third zip

floor 

 
-### Definition
-
-> [\<\{\}] \[[concat]\] [step]
-
-### Discussion
-
-Note that only one "level" of lists is flattened.  In the example above
-`[4]` is not unquoted.
-
-### Crosslinks
-
-[concat]
-[first]
-[first_two]
-[fourth]
-[getitem]
-[remove]
-[rest]
-[reverse]
-[rrest]
-[second]
-[shift]
-[shunt]
-[size]
-[sort]
-[split_at]
-[split_list]
-[swaack]
-[third]
-[zip]
-
-

floor 

-
-
-Function
 
 Return the largest integer \<= x.
+

Discussion

This function doesn't make sense (yet) to have because there are (as yet) +only integers in the system.

floordiv 

 
-### Discussion
-
-This function doesn't make sense (yet) to have because there are (as yet)
-only integers in the system.
-
-

floordiv 

-
-
-Function
 
 I don't know why this is called "floor" div, I think it rounds its
 result down (not towards zero or up.)
@@ -1301,17 +663,8 @@ result down (not towards zero or up.)
        a b floordiv
     ------------------
           (a/b)
-
-### Discussion
-
-All the division commands need to be revisited when the "numeric tower"
-for Thun gets nailed down.
-
-### Crosslinks
-
-[divmod]
-
-

fork

combinator

+

Discussion

All the division commands need to be revisited when the "numeric tower" +for Thun gets nailed down.

See Also

divmod

fork

combinator

 
 
 
@@ -1320,78 +673,25 @@ Run two quoted programs in parallel and replace them with their results.
        ... [F] [G] fork
     ----------------------
            ... f g
+

Definition

[i] app2

Discussion

The basic parallelism combinator, the two programs are run independently.

See Also

cleave clop map

Used By

cleave

fourth 

 
-### Definition
-
-> \[[i]\] [app2]
-
-### Discussion
-
-The basic parallelism combinator, the two programs are run independently.
-
-### Crosslinks
-
-[cleave]
-[clop]
-[map]
-
-

fourth 

-
-
-Function
 
 Replace a list with its fourth item.
 
        [a b c d ...] fourth
     --------------------------
               d
+

Definition

rest third

See Also

first second third rest

gcd 

 
-### Definition
-
-> [rest] [third]
-
-### Crosslinks
-
-[first]
-[second]
-[third]
-[rest]
-
-

gcd 

-
-
-Function
 
 Take two integers from the stack and replace them with their Greatest
 Common Denominator.
+

Definition

true [tuck mod dup 0 >] loop pop

Discussion

Euclid's Algorithm

gcd2 

 
-### Definition
-
-> true \[[tuck] [mod] [dup] 0 [>]\] [loop] [pop]
-
-### Discussion
-
-Euclid's Algorithm
-
-

gcd2 

-
-
-Function
 
 Compiled GCD function.
+

Discussion

See [gcd].

See Also

gcd

ge 

 
-### Discussion
-
-See [gcd].
-
-### Crosslinks
-
-[gcd]
-
-

ge 

-
-
-Function
 
 Greater-than-or-equal-to comparison of two numbers.
 
@@ -1399,17 +699,7 @@ Greater-than-or-equal-to comparison of two numbers.
     --------------
        Boolean
        (a >= b)
-
-### Crosslinks
-
-[cmp]
-[eq]
-[gt]
-[le]
-[lt]
-[ne]
-
-

genrec

combinator

+

Definition

[true] [true] [false] cmp

See Also

cmp eq gt le lt ne

genrec

combinator

 
 
 
@@ -1418,23 +708,13 @@ Greater-than-or-equal-to comparison of two numbers.
                           [if] [then] [rec1] [rec2] genrec
     ---------------------------------------------------------------------
        [if] [then] [rec1 [[if] [then] [rec1] [rec2] genrec] rec2] ifte
-
-### Definition
-
-> \[\[[genrec]\] [ccccons]\] [nullary] [swons] [concat] [ifte]
-
-(Note that this definition includes the `genrec` symbol itself, it is
+

Definition

[[genrec] ccccons] nullary swons concat ifte

Discussion

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.) - -### Discussion - +only self-referential definition. See the [Recursion Combinators notebook](https://joypy.osdn.io/notebooks/Recursion_Combinators.html). - From ["Recursion Theory and Joy"](https://www.kevinalbrecht.com/code/joy-mirror/j05cmp.html) by Manfred von Thun: - > "The genrec combinator 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 @@ -1445,43 +725,24 @@ by Manfred von Thun: > 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 way to design one of these is to fix your base case `[then]` and the test `[if]`, and then treat `rec1` and `rec2` as an else-part "sandwiching" a quotation of the whole function. - For example, given a (general recursive) function `F`: - F == [I] [T] [R1] [R2] genrec - If the `[I]` if-part fails you must derive `R1` and `R2` from: : - ... R1 [F] R2 - Just set the stack arguments in front, and figure out what `R1` and `R2` have to do to apply the quoted `[F]` in the proper way. In effect, the `genrec` combinator turns into an [ifte] combinator with a quoted copy of the original definition in the else-part: - F == [I] [T] [R1] [R2] genrec == [I] [T] [R1 [F] R2] ifte - Tail recursive functions are those where `R2` is the `i` combinator: - P == [I] [T] [R] tailrec == [I] [T] [R [P] i] ifte - == [I] [T] [R P] ifte + == [I] [T] [R P] ifte

See Also

anamorphism tailrec x

Used By

anamorphism genrec tailrec

getitem 

 
-### Crosslinks
-
-[anamorphism]
-[tailrec]
-[x]
-
-

getitem 

-
-
-Function
 
 Expects an integer and a quote on the stack and returns the item at the
 nth position in the quote counting from 0.
@@ -1491,42 +752,10 @@ nth position in the quote counting from 0.
        [a b c d] 2 getitem
     -------------------------
             c
-
-### Definition
-
-> [drop] [first]
-
-### Discussion
-
-If the number isn't a valid index into the quote `getitem` will cause
+

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.) +implementation-dependant.)

See Also

concat first first_two flatten fourth remove rest reverse rrest second shift shunt size sort split_at split_list swaack third zip

grabN 

 
-### Crosslinks
-
-[concat]
-[first]
-[first_two]
-[flatten]
-[fourth]
-[remove]
-[rest]
-[reverse]
-[rrest]
-[second]
-[shift]
-[shunt]
-[size]
-[sort]
-[split_at]
-[split_list]
-[swaack]
-[third]
-[zip]
-

grabN 

-
-
-Function
 
 Expect a number on the top of the stack and [cons] that many items from under it onto a new list.
 
@@ -1535,14 +764,8 @@ Expect a number on the top of the stack and [cons] that many items from under it
        a b c d e 3 grabN
     -----------------------
           a b [c d e]
+

Definition

<{} [cons] times

Used By

appN

grba 

 
-### Definition
-
-> [\<\{\}] \[[cons]\] [times]
-

grba 

-
-
-Function
 
 A weird function used in [app2] that does this:
 
@@ -1551,23 +774,9 @@ A weird function used in [app2] that does this:
        ... 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

[stack popd] dip

Discussion

This function "grabs" an item from the stack along with a copy of the stack. +It's part of the [app2] definition.

See Also

app2

Used By

app1 app2

gt 

 
-### Definition
-
-> \[[stack] [popd]\] [dip]
-
-### Discussion
-
-This function "grabs" an item from the stack along with a copy of the stack.
-It's part of the [app2] definition.
-
-### Crosslinks
-
-[app2]
-

gt 

-
-
-Function
 
 Greater-than comparison of two numbers.
 
@@ -1575,53 +784,22 @@ Greater-than comparison of two numbers.
     --------------
        Boolean
        (a > b)
+

Definition

[true] [false] [false] cmp

See Also

cmp eq ge le lt ne

help 

 
-### Crosslinks
-
-[cmp]
-[eq]
-[ge]
-[le]
-[lt]
-[ne]
-

help 

-
-
-Function
 
 Accepts a quoted symbol on the top of the stack and prints its
 documentation.
 
        [foo] help
     ----------------
+

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.

hypot 

 
-### 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.
-
-

hypot 

-
-
-Function
 
              x y hypot
     ---------------------------
        sqrt(sqr(x) + sqr(y))
-
-### Definition
-
-> \[[sqr]\] [ii] [+] [sqrt]
-
-### Discussion
-
-This is another function that has to wait on the numeric tower.
-
-### Crosslinks
-
-[sqrt]
-
-

i

combinator

+

Definition

[sqr] ii + sqrt

Discussion

This is another function that has to wait on the numeric tower.

See Also

sqrt

i

combinator

 
 
 
@@ -1631,23 +809,12 @@ 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`.

Used By

b fork ii infra pam tailrec unquoted x

id 

 
-### 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 

-
-
-Function
 
 The identity function.
-
-### Discussion
-
-Does nothing.  It's kind of a mathematical thing, but it occasionally comes in handy.
-

ifte

combinator

+

Discussion

Does nothing. It's kind of a mathematical thing, but it occasionally comes in handy.

ifte

combinator

 
 
 
@@ -1656,17 +823,7 @@ If-Then-Else combinator, a common and convenient specialization of [branch].
             [if] [then] [else] ifte
     ---------------------------------------
        [if] nullary [else] [then] branch
-
-### Definition
-
-> \[[nullary]\] [dipd] [swap] [branch]
-
-### Crosslinks
-
-[branch]
-[loop]
-[while]
-

ii

combinator

+

Definition

[nullary] dipd swap branch

See Also

branch loop while

Used By

cmp genrec spiral_next

ii

combinator

 
 
 
@@ -1677,10 +834,6 @@ top item, then again with the top item.
     ------------------
      ... Q a Q
 
-### Definition
-
-> \[[dip]\] [dupdip] [i]
-
 ### Example
 
 It's a little tricky to understand how this works so here's an example trace:
@@ -1694,24 +847,13 @@ It's a little tricky to understand how this works so here's an example trace:
           1 2 4 4 [++] • i
                1 2 4 4 • ++
                1 2 4 5 •
-
-### Discussion
-
-In some cases (like the example above) this is the same effect as using [app2] but most of the time it's not:
-
+

Definition

[dip] dupdip i

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 -------------------- 1 9 - 1 2 3 4 [+] app2 ---------------------- - 1 2 5 6 - -### Crosslinks - -[app2] -[b] -

infra

combinator

+           1 2 5 6

See Also

app2 b

Used By

app2 hypot spiral_next

infra

combinator

 
 
 
@@ -1722,10 +864,6 @@ the list as its stack.  Does not affect the stack (below the list.)
     ---------------------------------
         c b a Q [z y x ...] swaack
 
-### Definition
-
-> [swons] [swaack] \[[i]\] [dip] [swaack]
-
 
     ... [a b c] [F] swons swaack [i] dip swaack
     ... [[F] a b c]       swaack [i] dip swaack
@@ -1736,29 +874,15 @@ the list as its stack.  Does not affect the stack (below the list.)
     d e         [...]         swaack
     ... [e d]
 
-
-### Discussion
-
-This is one of the more useful combinators.  It allows a quoted
+

Definition

swons swaack [i] dip swaack

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 - -[swaack](#swaack) - -

infrst

combinator

+`infra` lets you work on its internal structure.

See Also

swaack

Used By

infrst range_to_zero run

infrst

combinator

 
 
 
 Does [infra] and then extracts the [first] item from the resulting list.
-
-### Definition
-
-> [infra] [first]
-
-

inscribe 

+

Definition

infra first

Used By

app1 app2 dinfrirst

inscribe 

 
 
 Create a new Joy function definition in the Joy dictionary. A definition
@@ -1767,18 +891,12 @@ is given as a quote with a name followed by a Joy expression.
 ### Example
 
     [sqr dup mul] inscribe
-
-### Discussion
-
-This is the only function that modifies the dictionary.  It's provided as a 
+

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 

+know what you're doing.

le 

 
 
-Function
-
 Less-Than-or-Equal-to comparison of the two items on the top of the
 stack, replacing them with a Boolean value.
 
@@ -1786,16 +904,7 @@ stack, replacing them with a Boolean value.
     -------------
        Boolean
        (a <= b)
-
-### Crosslinks
-
-[cmp]
-[eq]
-[ge]
-[gt]
-[lt]
-[ne]
-

loop

combinator

+

Definition

[false] [true] [true] cmp

See Also

cmp eq ge gt lt ne

loop

combinator

 
 
 
@@ -1809,44 +918,24 @@ discard the quoted program, otherwise run a copy of `Q` and `loop` again.
        true [Q] . loop
     --------------------------
                 . Q [Q] loop
-
-### Discussion
-
-This, along with [branch] and [fork], is one of the four main combinators
+

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](https://en.wikipedia.org/wiki/Joy_(programming_language)#Mathematical_purity), - > 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]. +[loop] has [while].

See Also

branch fork while

Used By

gcd while

lshift 

 
-### Crosslinks
-
-[branch]
-[fork]
-[while]
-

lshift 

-
-
-Function
 
 [Logical Left-Shift](https://en.wikipedia.org/wiki/Logical_shift)
 
        a n lshift
     ----------------
          (a×2ⁿ)
+

Definition

[2 *] times

See Also

rshift

Used By

<<

lt 

 
-### Crosslinks
-
-[rshift]
-

lt 

-
-
-Function
 
 Less-Than comparison of the two items on the top of the
 stack, replacing them with a Boolean value.
@@ -1855,19 +944,8 @@ stack, replacing them with a Boolean value.
     -------------
        Boolean
        (a < b)
+

Definition

[false] [false] [true] cmp

See Also

cmp eq ge gt le ne

make_generator 

 
-### Crosslinks
-
-[cmp]
-[eq]
-[ge]
-[gt]
-[le]
-[ne]
-

make_generator 

-
-
-Function
 
 Given an initial state value and a quoted generator function build a
 generator quote.
@@ -1887,20 +965,7 @@ And then:
        [230 [dup ++] codireco] 5 [x] times pop
     ---------------------------------------------
                  230 231 232 233 234
-
-### Definition
-
-> \[[codireco]\] [ccons]
-
-### Discussion
-
-See the ["Using `x` to Generate Values" notebook](https://joypy.osdn.io/notebooks/Generator_Programs.html#an-interesting-variation).
-
-### Crosslinks
-
-[codireco]
-
-

map

combinator

+

Definition

[codireco] ccons

Discussion

See the ["Using `x` to Generate Values" notebook](https://joypy.osdn.io/notebooks/Generator_Programs.html#an-interesting-variation).

See Also

codireco

map

combinator

 
 
 
@@ -1913,24 +978,9 @@ program with a list of the results.
        5 [1 2 3] [++ *] map
     --------------------------
            5 [10 15 20]
+

Definition

[_map0] cons [[] [_map?] [_mape]] dip tailrec

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.

See Also

app1 app2 app3 appN fork

Used By

appN pam

max 

 
-### 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
-
-[app1]
-[app2]
-[app3]
-[appN](#appn)
-[fork]
-
-

max 

-
-
-Function
 
 Given a list find the maximum.
 
@@ -1939,17 +989,8 @@ Given a list find the maximum.
        [1 2 3 4] max
     -------------------
              4
+

See Also

min size sum

min 

 
-### Crosslinks
-
-[min]
-[size]
-[sum]
-
-

min 

-
-
-Function
 
 Given a list find the minimum.
 
@@ -1958,54 +999,29 @@ Given a list find the minimum.
        [1 2 3 4] min
     -------------------
              1 
+

See Also

max size sum

mod 

 
-### Crosslinks
-
-[max]
-[size]
-[sum]
-
-

mod 

-
-
-Function
 
 Return the remainder of `a` divided by `b`.
 
        a b mod
     -------------
         (a%b)
-
-### Crosslinks
-
-[divmod]
-[mul]
-
-

modulus 

+

Definition

%

See Also

divmod mul

Used By

gcd

modulus 

 
 
 See [mod](#mod).
 
-

mul 

+

mul 

 
 
-Function
-
 Multiply two numbers.
 
        a b mul
     -------------
         (a×b)
+

See Also

div product

Used By

sqr

ne 

 
-### Crosslinks
-
-[div]
-[product]
-
-

ne 

-
-
-Function
 
 Not-Equal comparison of the two items on the top of the
 stack, replacing them with a Boolean value.
@@ -2014,33 +1030,16 @@ stack, replacing them with a Boolean value.
     -------------
        Boolean
        (a = b)
+

See Also

cmp eq ge gt le lt

neg 

 
-### Crosslinks
-
-[cmp]
-[eq]
-[ge]
-[gt]
-[le]
-[lt]
-

neg 

-
-
-Function
 
 Invert the sign of a number.
 
        a neg
     -----------
         -a
-### Definition
+

Definition

0 swap -

Used By

abs

not 

 
-> 0 [swap] [-]
-
-

not 

-
-
-Function
 
 Like [bool] but convert the item on the top of the stack to the inverse
 Boolean value.
@@ -2052,40 +1051,15 @@ Boolean value.
        false not
     ---------------
          true
- 
-### Definition
+

Definition

[true] [false] branch

See Also

bool

Used By

null xor

nulco 

 
-> [bool] \[true\] \[false\] [branch]
-
-### Crosslinks
-
-[bool]
-
-

nulco 

-
-
-Function
 
 Take the item on the top of the stack and [cons] it onto `[nullary]`.
 
          [F] nulco
     -------------------
        [[F] nullary]
-
-### Definition
-
-> \[[nullary]\] [cons]
-
-### Discussion
-
-Helper function for [\|\|] and [&&].
-
-### Crosslinks
-
-[&&]
-[\|\|]
-
-

nullary

combinator

+

Definition

[nullary] cons

Discussion

Helper function for [\|\|] and [&&].

See Also

&& ||

Used By

and or while

nullary

combinator

 
 
 
@@ -2096,10 +1070,6 @@ item of the result on the stack.
     ---------------------
             ... a
 
-### Definition
-
-> \[[stack]\] [dip] [infra] [first]
-
 ### Example
 
     ... [P] nullary
@@ -2108,23 +1078,10 @@ item of the result on the stack.
     ... [...] [P] infra first
     ... [a ...] first
     ...  a
-
-### Discussion
-
-A very useful function that runs any other quoted function and returns
+

Definition

[stack] dinfrirst

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.) +program.)

See Also

unary binary ternary

Used By

and genrec ifte nulco or unary

of 

 
-### Crosslinks
-
-[unary](#unary)
-[binary](#binary)
-[ternary](#ternary)
-
-

of 

-
-
-Function
 
 Like [getitem] but [swap]s the order of arguments.
 
@@ -2133,31 +1090,12 @@ Like [getitem] but [swap]s the order of arguments.
        2 [a b c d] of
     --------------------
              c
+

Definition

swap at

See Also

getitem

or 

 
-### Definition
-
-> [swap] [getitem]
-
-### Crosslinks
-
-[getitem]
-
-

or 

-
-
-Function
 
 Logical bit-wise OR.
+

Definition

nulco [nullary] dip [true] branch

See Also

and xor

Used By

spiral_next

over 

 
-### Crosslinks
-
-[and]
-[xor]
-
-

over 

-
-
-Function
 
 [dup] the second item on the stack `over` the first.
 
@@ -2180,16 +1118,7 @@ There are many many ways to define this function.
 > [unit] [dupdipd] [first]
 
 And so on...
-
-### Discussion
-
-A fine old word from Forth.
-
-### Crosslinks
-
-[tuck]
-
-

pam

combinator

+

Definition

[dup] dip swap

Discussion

A fine old word from Forth.

See Also

tuck

pam

combinator

 
 
 
@@ -2202,203 +1131,73 @@ rest of the stack.)
        5 7 [[+][-][*][/][%]] pam
     -------------------------------
           5 7 [12 -2 35 0 5]
-
-### Definition
-
-> \[[i]\] [map]
-
-### Discussion
-
-A specialization of [map] that runs a list of functions in parallel (if
-the underlying [map] function is so implemented, of course.)
-
-### Crosslinks
-
-[map]
-
-

pick 

+

Definition

[i] map

Discussion

A specialization of [map] that runs a list of functions in parallel (if +the underlying [map] function is so implemented, of course.)

See Also

map

pick 

 
 
 See [getitem](#getitem).
 
-

pm 

+

pm 

 
 
-Function
-
 Plus or minus.  Replace two numbers with their sum and difference.
 
           a b pm
     -----------------
        (a+b) (a-b)
+

Definition

[+] [-] clop

pop 

 
-### Definition
-
-> \[+\] \[-\] [clop]
-
-

pop 

-
-
-Function
 
 Pop the top item from the stack and discard it.
 
        a pop
     -----------
+

See Also

popd popdd popop popopd popopdd popopop

Used By

/\ \/ anamorphism clear disenstacken first gcd popd popdd popop popopop size small spiral_next take unstack

popd 

 
-### Crosslinks
-
-[popd]
-[popdd]
-[popop]
-[popopd]
-[popopdd]
-[popopop]
-
-

popd 

-
-
-Function
 
 [pop] the second item down on the stack.
 
        a b popd
     --------------
           b
+

Definition

[pop] dip

See Also

pop popdd popop popopd popopdd popopop

Used By

binary grba rest ternary unary

popdd 

 
-### Definition
-
-> [swap] [pop]
-
-### Crosslinks
-
-[pop]
-[popdd]
-[popop]
-[popopd]
-[popopdd]
-[popopop]
-
-

popdd 

-
-
-Function
 
 [pop] the third item on the stack.
 
        a b c popdd
     -----------------
            b c
+

Definition

[pop] dipd

See Also

pop popd popop popopd popopdd popopop

Used By

cleave clop

popop 

 
-### Definition
-
-> [rolldown] [pop]
-
-### Crosslinks
-
-[pop]
-[popd]
-[popop]
-[popopd]
-[popopdd]
-[popopop]
-
-

popop 

-
-
-Function
 
 [pop] two items from the stack.
 
        a b popop
     ---------------
+

Definition

pop pop

See Also

pop popd popdd popopd popopdd popopop

Used By

popopd popopdd popopop

popopd 

 
-### Definition
-
-> [pop] [pop]
-
-### Crosslinks
-
-[pop]
-[popd]
-[popdd]
-[popopd]
-[popopdd]
-[popopop]
-
-

popopd 

-
-
-Function
 
 [pop] the second and third items from the stack.
 
        a b c popopd
     ------------------
             c
+

Definition

[popop] dip

See Also

pop popd popdd popop popopdd popopop

popopdd 

 
-### Definition
-
-> [rollup] [popop]
-
-### Crosslinks
-
-[pop]
-[popd]
-[popdd]
-[popop]
-[popopdd]
-[popopop]
-
-

popopdd 

-
-
-Function
 
        a b c d popopdd
     ---------------------
             c d
+

Definition

[popop] dipd

See Also

pop popd popdd popop popopd popopop

popopop 

 
-### Definition
-
-> \[[popop]\] [dipd]
-
-### Crosslinks
-
-[pop]
-[popd]
-[popdd]
-[popop]
-[popopd]
-[popopop]
-
-

popopop 

-
-
-Function
 
 [pop] three items from the stack.
 
        a b c popopop
     -------------------
+

Definition

pop popop

See Also

pop popd popdd popop popopd popopdd

pow 

 
-### Definition
-
-> [pop] [popop]
-
-### Crosslinks
-
-[pop]
-[popd]
-[popdd]
-[popop]
-[popopd]
-[popopdd]
-
-

pow 

-
-
-Function
 
 Take two numbers `a` and `n` from the stack and raise `a` to the `n`th
 power.  (`n` is on the top of the stack.)
@@ -2413,22 +1212,11 @@ power.  (`n` is on the top of the stack.)
     -----------------------------------
         2 [4 8 16 32 64 128 256 512]
 
-

pred 

+

Definition

1 roll> swap [*] cons times

pred 

 
 
-Function
-
 Predecessor. Decrement TOS.
-
-### Definition
-
-> 1 -
-
-### Crosslinks
-
-[succ]
-
-

primrec

combinator

+

See Also

succ

primrec

combinator

 
 
 
@@ -2459,21 +1247,9 @@ From the ["Overview of the language JOY"](https://www.kevinalbrecht.com/code/joy
              n [Base] [Recur] primrec
     ------------------------------------------ n > 0
        n (n-1) [Base] [Recur] primrec Recur
+

Discussion

Simple and useful specialization of the [genrec] combinator from the +[original Joy system](https://www.kevinalbrecht.com/code/joy-mirror/index.html).

See Also

genrec tailrec

product 

 
-### Discussion
-
-Simple and useful specialization of the [genrec] combinator from the
-[original Joy system](https://www.kevinalbrecht.com/code/joy-mirror/index.html).
-
-### Crosslinks
-
-[genrec]
-[tailrec]
-
-

product 

-
-
-Function
 
 Just as [sum] sums a list of numbers, this function multiplies them
 together.
@@ -2487,33 +1263,16 @@ Or,
 > \[1\] \[[mul]\] [primrec]
 
 
-

quoted 

+

Definition

1 swap [*] step

quoted 

 
 
-Function
-
 "Quote D" Wrap the second item on the stack in a list.
 
        a b quoted
     ----------------
          [a] b
+

Definition

[unit] dip

Discussion

This comes from the original Joy stuff.

See Also

unit

range 

 
-### Definition
-
-> \[[unit]\] [dip]
-
-### Discussion
-
-This comes from the original Joy stuff.
-
-### Crosslinks
-
-[unit]
-
-

range 

-
-
-Function
 
 Expect a number `n` on the stack and replace it with a list:
 `[(n-1)...0]`.
@@ -2527,23 +1286,8 @@ Expect a number `n` on the stack and replace it with a list:
        -5 range
     --------------
           []
+

Definition

[0 <=] [-- dup] anamorphism

Discussion

If `n` is less than 1 the resulting list is empty.

See Also

range_to_zero

range_to_zero 

 
-### Definition
-
-> \[0 \<=\] \[1 - [dup]\] [anamorphism]
-
-### Discussion
-
-If `n` is less than 1 the resulting list is empty.
-
-### Crosslinks
-
-[range_to_zero]
-
-

range_to_zero 

-
-
-Function
 
 Take a number `n` from the stack and replace it with a list
 `[0...n]`.
@@ -2553,55 +1297,27 @@ Take a number `n` from the stack and replace it with a list
        5 range_to_zero
     ---------------------
         [0 1 2 3 4 5]
+

Definition

unit [down_to_zero] infra

Discussion

Note that the order is reversed compared to [range].

See Also

down_to_zero range

reco 

 
-### Definition
-
-> [unit] \[[down_to_zero]\] [infra]
-
-### Discussion
-
-Note that the order is reversed compared to [range].
-
-### Crosslinks
-
-[down_to_zero]
-[range]
-
-

reco 

-
-
-Function
 
 Replace the first item in a list with the item under it.
 
        a [b ...] reco
     --------------------
          [a ...]
-
-### Definition
-
-> [rest] [cons]
-
-### Crosslinks
-
-[codireco]
-[make_generator]
-
-

rem 

+

Definition

rest cons

See Also

codireco make_generator

Used By

codireco

rem 

 
 
 See [mod](#mod).
 
-

remainder 

+

remainder 

 
 
 See [mod](#mod).
 
-

remove 

+

remove 

 
 
-Function
-
 Expects an item on the stack and a quote under it and removes that item
 from the the quote. The item is only removed once. If the list is empty
 or the item isn't in the list then the list is unchanged.
@@ -2614,24 +1330,14 @@ or the item isn't in the list then the list is unchanged.
 
 See the ["Remove Function" notebook](https://osdn.net/projects/joypy/scm/git/Thun/blobs/master/docs/notebooks/Remove-Function.ipynb).
 
-

rest 

+

rest 

 
 
-Function
-
        [a ...] rest
     ------------------
           [...]
+

Definition

uncons popd

See Also

first uncons

Used By

drop fourth reco rrest second small third uncons

reverse 

 
-### Crosslinks
-
-[first]
-[uncons]
-
-

reverse 

-
-
-Function
 
 Reverse the list on the top of the stack.
 
@@ -2641,100 +1347,49 @@ Reverse the list on the top of the stack.
     ---------------------
            [3 2 1]
 
-### Definition
-
-> [\<\{\}] [shunt]
-
-

roll< 

+

Definition

<{} shunt

Used By

appN split_list

roll< 

 
 
 See [rolldown](#rolldown).
 
-

roll> 

+

Definition

swapd swap

Used By

rolldown

roll> 

 
 
 See [rollup](#rollup).
 
-

rolldown 

+

Definition

swap swapd

Used By

pow rollup step_zero

rolldown 

 
 
-Function
-
        a b c rolldown
     --------------------
            b c a
+

Definition

roll<

See Also

rollup

rollup 

 
-### Definition
-
-> [swapd] [swap]
-
-### Crosslinks
-
-[rollup]
-
-

rollup 

-
-
-Function
 
        a b c rollup
     ------------------
           c a b
+

Definition

roll>

See Also

rolldown

Used By

<<{}

round 

 
-### Definition
-
-> [swap] [swapd]
-
-### Crosslinks
-
-[rolldown]
-
-

round 

-
-
-Function
 
 Round a number to a given precision in decimal digits.
+

Discussion

Another one that won't make sense until the "numeric tower" is nailed +down.

rrest 

 
-### Discussion
-
-Another one that won't make sense until the "numeric tower" is nailed
-down.
-
-

rrest 

-
-
-Function
 
        [a b ...] rrest
     ---------------------
             [...]
-### Definition
+

Definition

rest rest

See Also

rest

rshift 

 
-> [rest] [rest]
-
-### Crosslinks
-
-[rest]
-
-

rshift 

-
-
-Function
 
 [Logical Right-Shift](https://en.wikipedia.org/wiki/Logical_shift)
 
        a n rshift
     ----------------
          (a∕2ⁿ)
+

Definition

[2 /] times

See Also

lshift

Used By

>>

run 

 
-### Crosslinks
-
-[lshift]
-

run 

-
-
-Function
 
 Run a quoted program in a list.
 
@@ -2743,34 +1398,14 @@ Run a quoted program in a list.
        [1 2 +] run
     -----------------
            [3]
+

Definition

<{} infra

second 

 
-### Definition
-
-> [\<\{\}] [infra]
-
-

second 

-
-
-Function
 
        [a b ...] second
     ----------------------
               b
+

Definition

rest first

See Also

first third fourth

Used By

third

select 

 
-### Definition
-
-> [rest] [first]
-
-### Crosslinks
-
-[first]
-[third]
-[fourth]
-
-

select 

-
-
-Function
 
 Use a Boolean value to select one of two items from a sequence. :
 
@@ -2781,35 +1416,13 @@ Use a Boolean value to select one of two items from a sequence. :
        [a b] true select
     -----------------------
                b
+

Discussion

The sequence can contain more than two items but not fewer.

See Also

choice

sharing 

 
-### Discussion
-
-The sequence can contain more than two items but not fewer.
-
-### Crosslinks
-
-[choice]
-
-

sharing 

-
-
-Function
 
 Print redistribution information.
+

Discussion

Mathematically this is a form of [id], but it has the side-effect of +printing out the GPL notice.

See Also

warranty

shift 

 
-### Discussion
-
-Mathematically this is a form of [id], but it has the side-effect of
-printing out the GPL notice.
-
-### Crosslinks
-
-[warranty]
-
-

shift 

-
-
-Function
 
 Move the top item from one list to another.
 
@@ -2818,19 +1431,8 @@ Move the top item from one list to another.
        [x y z] [a b c] shift
     ---------------------------
           [a x y z] [b c]
+

Definition

uncons [swons] dip

See Also

shunt

Used By

take

shunt 

 
-### Definition
-
-> [uncons] \[[swons]\] [dip]
-
-### Crosslinks
-
-[shunt]
-
-

shunt 

-
-
-Function
 
 Like [concat] but [reverse] the top list into the second.
 
@@ -2839,26 +1441,9 @@ Like [concat] but [reverse] the top list into the second.
        [a b c] [d e f] shunt
     ---------------------------
            [f e d a b c] 
+

Definition

[swons] step

Discussion

This is more efficient than [concat] so prefer it if you don't need to +preserve order.

See Also

concat reverse shift

Used By

reverse

size 

 
-### Definition
-
-> \[[swons]\] [step]
-
-### Discussion
-
-This is more efficient than [concat] so prefer it if you don't need to
-preserve order.
-
-### Crosslinks
-
-[concat]
-[reverse]
-[shift]
-
-

size 

-
-
-Function
 
 Replace a list with its size.
 
@@ -2868,14 +1453,8 @@ Replace a list with its size.
     ------------------------
                3
 
-### Definition
+

Definition

[pop ++] step_zero

Used By

average

sort 

 
-> \[[pop] [++]\] [step_zero]
-
-

sort 

-
-
-Function
 
 Given a list return it sorted.
 
@@ -2885,21 +1464,12 @@ Given a list return it sorted.
     ----------------------
           [1 2 4 5 7]
 
-

spiral_next 

+

spiral_next 

 
 
-Function
-
 Example code.
+

Definition

[[[abs] ii <=] [[<>] [pop !-] or] and] [[!-] [[++]] [[--]] ifte dip] [[pop !-] [--] [++] ifte] ifte

Discussion

See the ["Square Spiral Example Joy Code" notebook](https://joypy.osdn.io/notebooks/Square_Spiral.html).

split_at 

 
-### Discussion
-
-See the ["Square Spiral Example Joy Code" notebook](https://joypy.osdn.io/notebooks/Square_Spiral.html).
-
-

split_at 

-
-
-Function
 
 Split a list (second on the stack) at the position given by the number on
 the top of the stack.
@@ -2909,25 +1479,10 @@ the top of the stack.
        [1 2 3 4 5 6 7] 4 split_at
     --------------------------------
            [5 6 7] [4 3 2 1]
-
-### Definition
-
-> \[[drop]\] \[[take]\] [clop]
-
-### Discussion
-
-Take a list and a number `n` from the stack, take `n` items from the top
+

Definition

[drop] [take] clop

Discussion

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. +on the top of the stack.

See Also

split_list

split_list 

 
-### Crosslinks
-
-[split_list]
-
-

split_list 

-
-
-Function
 
 Split a list (second on the stack) at the position given by the number on
 the top of the stack such that [concat] would reconstruct the original
@@ -2936,77 +1491,33 @@ list.
        [1 2 3 4 5 6 7] 4 split_list
     ----------------------------------
             [1 2 3 4] [5 6 7]
+

Definition

[take reverse] [drop] clop

Discussion

Compare with [split_at]. This function does extra work to ensure that +[concat] would reconstruct the original list.

See Also

split_at

sqr 

 
-### Definition
-
-> \[[take] [reverse]\] \[[drop]\] [clop]
-
-### Discussion
-
-Compare with [split_at].  This function does extra work to ensure that
-[concat] would reconstruct the original list.
-
-### Crosslinks
-
-[split_at]
-
-

sqr 

-
-
-Function
 
 Square the number on the top of the stack.
 
        n  sqr
     ------------
          n²
-
-### Definition
-
-> [dup] [mul]
-
-

sqrt 

+

Definition

dup mul

Used By

hypot

sqrt 

 
 
 Function Combinator
 
 Return the square root of the number a. Negative numbers return complex
 roots.
+

Discussion

Another "numeric tower" hatch...

Used By

hypot

stack 

 
-### Discussion
-
-Another "numeric tower" hatch...
-
-

stack 

-
-
-Function
 
 Put the stack onto the stack.
 
           ... c b a stack
     ---------------------------
        ... c b a [a b c ...]
+

Discussion

This function forms a pair with [unstack], and together they form the +complement to the "destructive" pair [enstacken] and [disenstacken].

See Also

enstacken disenstacken

Used By

enstacken grba nullary stackd stuncons

stackd 

 
-### Definition
-
-> \[\] [swaack] [dup] [swaack] [first]
-
-### Discussion
-
-This function forms a pair with [unstack], and together they form the
-complement to the "destructive" pair [enstacken] and [disenstacken].
-
-### Crosslinks
-
-[unstack]
-[enstacken]
-[disenstacken]
-
-

stackd 

-
-
-Function
 
 Grab the stack under the top item and put it onto the stack.
 
@@ -3016,11 +1527,7 @@ Grab the stack under the top item and put it onto the stack.
     ------------------------
       ... 1 2 [2 1 ...] 3
 
-### Definition
-
-> \[[stack]\] [dip]
-
-

step

combinator

+

Definition

[stack] dip

step

combinator

 
 
 
@@ -3039,16 +1546,7 @@ Run a quoted program on each item in a sequence.
        ... [a b c] [Q] . step
     ----------------------------------------
                  ... a . Q [b c] [Q] step
-
-### Discussion
-
-See the [Recursion Combinators notebook](https://joypy.osdn.io/notebooks/Recursion_Combinators.html).
-
-### Crosslinks
-
-[step_zero]
-
-

step_zero

combinator

+

Definition

[_step0] x

Discussion

See the [Recursion Combinators notebook](https://joypy.osdn.io/notebooks/Recursion_Combinators.html).

See Also

step_zero

Used By

flatten product shunt step_zero

step_zero

combinator

 
 
 
@@ -3057,24 +1555,9 @@ Like [step] but with 0 as the initial value.
        [...] [F] step_zero
     -------------------------
          0 [...] [F] step
+

Definition

0 roll> step

Discussion

[size] and [sum] can both be defined in terms of this specialization of +[step].

See Also

step

Used By

size sum

stuncons 

 
-### Definition
-
-> 0 [roll>] [step]
-
-### Discussion
-
-[size] and [sum] can both be defined in terms of this specialization of
-[step].
-
-### Crosslinks
-
-[step]
-
-

stuncons 

-
-
-Function
 
 Take the [stack] and [uncons] the top item.
 
@@ -3083,15 +1566,8 @@ Take the [stack] and [uncons] the top item.
        1 2 3 stuncons
     --------------------
        1 2 3 3 [2 1]
+

Definition

stack uncons

stununcons 

 
-### Definition
-
-> [stack] [uncons]
-
-

stununcons 

-
-
-Function
 
 Take the [stack] and [uncons] the top two items.
 
@@ -3100,46 +1576,19 @@ Take the [stack] and [uncons] the top two items.
        1 2 3 stununcons
     ----------------------
         1 2 3 3 2 [1]
+

See Also

stuncons

sub 

 
-### Definition
-
-> [stack] [uncons] [uncons]
-
-### Crosslinks
-
-[stuncons]
-
-

sub 

-
-
-Function
 
 Subtract the number on the top of the stack from the number below it.
 
        a b sub
     -------------
         (a-b)
+

See Also

add

succ 

 
-### Crosslinks
-
-[add]
-
-

succ 

-
-
-Function
 
 Successor. Increment TOS.
-
-### Definition
-
-> 1 +
-
-### Crosslinks
-
-[pred]
-
-

sum

combinator

+

See Also

pred

sum

combinator

 
 
 
@@ -3150,19 +1599,8 @@ Given a quoted sequence of numbers return the sum.
        [1 2 3 4 5] sum
     ---------------------
              15
+

Definition

[+] step_zero

See Also

size

Used By

average

swaack 

 
-### Definition
-
-> \[+\] [step_zero]
-
-### Crosslinks
-
-[size]
-
-

swaack 

-
-
-Function
 
 Swap stack.  Take a list from the top of the stack, replace the stack
 with the list, and put the old stack onto it.
@@ -3172,70 +1610,29 @@ with the list, and put the old stack onto it.
        1 2 3 [4 5 6] swaack
     --------------------------
        6 5 4 [3 2 1]
+

Discussion

This function works as a kind of "context switch". It's used in the +definition of [infra].

See Also

infra

Used By

clear disenstacken infra unstack

swap 

 
-### Discussion
-
-This function works as a kind of "context switch".  It's used in the
-definition of [infra].
-
-### Crosslinks
-
-[infra]
-
-

swap 

-
-
-Function
 
 Swap the top two items on the stack.
 
        a b swap
     --------------
          b a
+

See Also

swapd

Used By

<{} anamorphism app2 cmp ifte neg null of over pow product roll< roll> swapd swoncat swons unswons while

swapd 

 
-### Crosslinks
-
-[swapd]
-
-

swapd 

-
-
-Function
 
 Swap the second and third items on the stack.
 
        a b c swapd
     -----------------
           b a c
+

Definition

[swap] dip

See Also

over tuck

Used By

roll< roll> tuck

swoncat 

 
-### Definition
-
-> \[[swap]\] [dip]
-
-### Crosslinks
-
-[over]
-[tuck]
-
-

swoncat 

-
-
-Function
 
 [concat] two lists, but [swap] the lists first.
+

Definition

swap concat

See Also

concat

Used By

unstack

swons 

 
-### Definition
-
-> [swap] [concat]
-
-### Crosslinks
-
-[concat]
-
-

swons 

-
-
-Function
 
 Like [cons] but [swap] the item and list.
 
@@ -3243,37 +1640,17 @@ Like [cons] but [swap] the item and list.
     -------------------
           [a ...]
 
-### Definition
-
-> [swap] [cons]
-
-

tailrec

combinator

+

Definition

swap cons

Used By

anamorphism cmp genrec infra shift shunt

tailrec

combinator

 
 
 
 A specialization of the [genrec] combinator.
-
-### Definition
-
-> \[[i]\] [genrec]
-
-### Discussion
-
-Some recursive functions do not need to store additional data or pending
+

Definition

[i] genrec

Discussion

Some recursive functions do not need to store additional data or pending actions per-call. These are called ["tail recursive" functions](https://en.wikipedia.org/wiki/Tail_recursive). In Joy, they appear as [genrec] definitions that have [i] for the second half of their recursive branch. +See the [Recursion Combinators notebook](https://joypy.osdn.io/notebooks/Recursion_Combinators.html).

See Also

genrec

Used By

map

take 

 
-See the [Recursion Combinators notebook](https://joypy.osdn.io/notebooks/Recursion_Combinators.html).
-
-### Crosslinks
-
-[genrec]
-
-

take 

-
-
-Function
 
 Expects an integer `n` and a list on the stack and replace them with a list
 with just the top `n` items in reverse order.
@@ -3281,12 +1658,7 @@ with just the top `n` items in reverse order.
        [a b c d] 2 take
     ----------------------
             [b a]
-
-### Definition
-
-> [\<\<\{\}] \[[shift]\] [times] [pop]
-
-

ternary

combinator

+

Definition

<<{} [shift] times pop

Used By

split_at split_list

ternary

combinator

 
 
 
@@ -3296,43 +1668,14 @@ item of the result on the stack.
        ... z y x [P] ternary
     -------------------------
              ... a
+

Definition

binary popd

Discussion

Runs any other quoted function and returns its first result while +consuming exactly three items from the stack.

See Also

binary nullary unary

third 

 
-### Definition
-
-> [binary] [popd]
-
-### Discussion
-
-Runs any other quoted function and returns its first result while
-consuming exactly three items from the stack.
-
-### Crosslinks
-
-[binary](#binary)
-[nullary](#nullary)
-[unary](#unary)
-
-

third 

-
-
-Function
 
        [a b c ...] third
     -----------------------
                c
-
-### Definition
-
-> [rest] [second]
-
-### Crosslinks
-
-[first]
-[second]
-[fourth]
-[rest]
-
-

times

combinator

+

Definition

rest second

See Also

first second fourth rest

Used By

fourth

times

combinator

 
 
 
@@ -3351,57 +1694,35 @@ program `n` times.
     -------------------------------------  w/ n > 1
              ... . Q (n-1) [Q] times
 
-### Definition
-
-> \[\-- dip\] cons \[swap\] infra \[0 \>\] swap while pop :
-
-
-### Discussion
-
-This works by building a little [while] program and running it:
-
+

Definition

[_times0] x

Discussion

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 1 3 [[++] -- dip] • [swap] infra [0 >] swap while pop - 1 3 [[++] -- dip] [swap] • infra [0 >] swap while pop + 1 3 [[++] -- dip] [swap] • infra [0 >] swap while pop dip -- [++] • swap [3 1] swaack [0 >] swap while pop dip [++] -- • [3 1] swaack [0 >] swap while pop dip [++] -- [3 1] • swaack [0 >] swap while pop 1 3 [-- [++] dip] • [0 >] swap while pop - 1 3 [-- [++] dip] [0 >] • swap while pop - 1 3 [0 >] [-- [++] dip] • while pop - + 1 3 [-- [++] dip] [0 >] • swap while pop + 1 3 [0 >] [-- [++] dip] • while pop This 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. - -

truthy 

+in Lisp, or preprocessor directives in C.

Used By

drop grabN lshift pow rshift take

truthy 

 
 
 See [bool](#bool).
 
-

tuck 

+

tuck 

 
 
-Function
-
 [dup] the item on the top of the stack under the second item on the
 stack.
 
        a b tuck
     --------------
         b a b
-
-### Definition
-
-> [dup] \[[swap]\] [dip]
-
-### Crosslinks
-
-[over]
-
-

unary 

+

Definition

dup swapd

See Also

over

Used By

gcd

unary 

 
 
 (Combinator)
@@ -3412,26 +1733,9 @@ item of the result on the stack.
        ... x [P] unary
     ---------------------
            ... a
+

Definition

nullary popd

Discussion

Runs any other quoted function and returns its first result while +consuming exactly one item from the stack.

See Also

binary nullary ternary

Used By

binary

uncons 

 
-### Definition
-
-> [nullary] [popd]
-
-### Discussion
-
-Runs any other quoted function and returns its first result while
-consuming exactly one item from the stack.
-
-### Crosslinks
-
-[binary](#binary)
-[nullary](#nullary)
-[ternary](#ternary)
-
-

uncons 

-
-
-Function
 
 Removes an item from a list and leaves it on the stack under the rest of
 the list.  You cannot `uncons` an item from an empty list.
@@ -3439,36 +1743,18 @@ the list.  You cannot `uncons` an item from an empty list.
        [a ...] uncons
     --------------------
           a [...]
+

Definition

[first] dupdip rest

Discussion

This is the inverse of [cons].

See Also

cons

Used By

first rest shift stuncons unswons

unique 

 
-### Discussion
-
-This is the inverse of [cons].
-
-### Crosslinks
-
-[cons]
-
-

unique 

-
-
-Function
 
 Given a list remove duplicate items.
 
-

unit 

+

unit 

 
 
-Function
-
        a unit
     ------------
         [a]
-
-### Definition
-
-> \[\] [cons]
-
-

unquoted

combinator

+

Definition

[] cons

Used By

quoted range_to_zero

unquoted

combinator

 
 
 
@@ -3479,49 +1765,25 @@ Unquote (using [i]) the list that is second on the stack.
        1 2 [3 4] 5 unquoted
     --------------------------
              1 2 3 4 5
+

Definition

[i] dip

See Also

unit

unswons 

 
-### Definition
-
-> \[[i]\] [dip]
-
-### Crosslinks
-
-[unit]
-
-

unswons 

-
-
-Function
 
        [a ...] unswons
     ---------------------
            [...] a
 
-### Definition
+

Definition

uncons swap

void 

 
-> [uncons] [swap]
-
-

void 

-
-
-Function
 
 True if the form on TOS is void otherwise False.
-
-### Discussion
-
-A form is any Joy expression composed solely of lists.
+

Discussion

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](http://www.markability.net/) +"Laws of Form", see [The Markable Mark](http://www.markability.net/)

warranty 

 
-

warranty 

-
-
-Function
 
 Print warranty information.
 
-

while

combinator

+

while

combinator

 
 
 
@@ -3534,31 +1796,11 @@ and runs it [nullary].
         [P] [F] while
     --------------------- P -> true
        F [P] [F] while
+

Definition

swap nulco dupdipd concat loop

See Also

loop

Used By

down_to_zero

words 

 
-### Definition
-
-> [swap] [nulco] [dupdipd] [concat] [loop]
-
-### Crosslinks
-
-[loop]
-
-

words 

-
-
-Function
 
 Print all the words in alphabetical order.
-
-### Discussion
-
-Mathematically this is a form of [id].
-
-### Crosslinks
-
-[help]
-
-

x

combinator

+

Discussion

Mathematically this is a form of [id].

See Also

help

x

combinator

 
 
 
@@ -3568,36 +1810,15 @@ the stack.
        [F] x
     -----------
        [F] F
-
-### Definition
-
-    dup i
-
-### Discussion
-
-The simplest recursive pattern.
-
+

Definition

dup i

Discussion

The simplest recursive pattern. See the [Recursion Combinators notebook](https://joypy.osdn.io/notebooks/Recursion_Combinators.html). as well as -[Recursion Theory and Joy](https://www.kevinalbrecht.com/code/joy-mirror/j05cmp.html) by Manfred von +[Recursion Theory and Joy](https://www.kevinalbrecht.com/code/joy-mirror/j05cmp.html) by Manfred von

Used By

step times

xor 

 
 
-

xor 

-
-
-Function
-
 Logical bit-wise eXclusive OR.
+

Definition

[] [not] branch

See Also

and or

zip 

 
-### Crosslinks
-
-[and]
-[or]
-
-

zip 

-
-
-Function
 
 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.
@@ -3607,39 +1828,19 @@ 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]]
-

||

combinator

+

||

combinator

 
 
 
 Short-circuiting Boolean OR
 
-
-### Definition
-
-> [nulco](#nulco) \[[nullary](#nullary)\] [dip](#dip) \[true\] [branch](#branch)
-
-### Discussion
-
-Accept two quoted programs, run the first and expect a Boolean value, if
+

Discussion

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 - -### Crosslinks - -[&&](#section-1) -

• 

-
-
-See [id](#id).
-
-
+ true

See Also

&&
diff --git a/docs/html/css/func_ref.css b/docs/html/css/func_ref.css index d33f775..0a6c7c6 100644 --- a/docs/html/css/func_ref.css +++ b/docs/html/css/func_ref.css @@ -2,7 +2,7 @@ body { background: #fff; color: black; - font-family: 'EB Garamond 12'; + font-family: 'EB Garamond 16'; } footer { @@ -21,7 +21,7 @@ pre { margin-left: 2em; margin-right: 2em; margin-bottom: 1em; - font-family: 'Inconsolata'; + font-family: monospace, 'Inconsolata'; padding: 0.5em; } @@ -50,9 +50,12 @@ a.self_link:hover { font-family: monospace, 'Inconsolata'; } - span.kind { color: #fff; background: #555; padding: 0.1em; } + +h3 { + margin-bottom: 0.1em; +} diff --git a/docs/reference/Function-Reference.md b/docs/reference/Function-Reference.md index 97ff124..c285f3a 100644 --- a/docs/reference/Function-Reference.md +++ b/docs/reference/Function-Reference.md @@ -10,21 +10,12 @@ Each function, combinator, or definition should be documented here. ## abs -Function - Return the absolute value of the argument. -### Definition - -> [dup](#dup) 0 < [] \[[neg](#neg)\] [branch](#branch) - - ------------------------------------------------------------------------ ## add -Function - Add two numbers together: a + b. @@ -90,10 +81,6 @@ predicate `P`. ----------------------------------------- [P] [pop []] [G] [dip swons] genrec -### Definition - -> \[[pop](#pop) \[\]\] [swap](#swap) \[[dip](#dip) [swons](#swons)\] [genrec](#genrec) - ### Example The `range` function generates a list of the integers from 0 to n - 1: @@ -109,8 +96,6 @@ See the [Recursion Combinators notebook](https://joypy.osdn.io/notebooks/Recursi ## and -Function - Logical bit-wise AND. ### Crosslinks @@ -137,10 +122,6 @@ the first result of the program. This is the same effect as the [unary](#unary) combinator. -### Definition - -> [nullary](#nullary) [popd](#popd) - ### Discussion Just a specialization of `nullary` really. Its parallelizable cousins @@ -167,9 +148,6 @@ Like [app1](#app1) with two items. ... [y ...] [Q] . infra first [x ...] [Q] infra first -### Definition - -> \[[grba] [swap] [grba] [swap]\] [dip] \[[infrst]\] [cons] [ii] ### Discussion @@ -205,10 +183,6 @@ Like [app1] with three items. [y ...] [Q] infra first [x ...] [Q] infra first -### Definition - -> 3 [appN] - ### Discussion See [app2]. @@ -237,10 +211,6 @@ Like [app1] with any number of items. [x1 ...] [Q] infra first [x0 ...] [Q] infra first -### Definition - -> \[[grabN]\] [codi] [map] [disenstacken] - ### Discussion This function takes a quoted function `Q` and an integer and runs the @@ -272,16 +242,10 @@ See [getitem](#getitem). ## average -Function - Compute the average of a list of numbers. (Currently broken until I can figure out what to do about "numeric tower" in Thun.) -### Definition - -> \[[sum]\] \[[size]\] [cleave] [/] - ### Discussion Theoretically this function would compute the sum and the size in two @@ -306,10 +270,6 @@ item of the result on the stack. ----------------------- ... a -### Definition - -> [unary] [popd] - ### Discussion Runs any other quoted function and returns its first result while @@ -334,10 +294,6 @@ Run two quoted programs --------------- P Q -### Definition - -> \[[i]\] [dip] [i] - ### Discussion This combinator may seem trivial but it comes in handy. @@ -352,8 +308,6 @@ This combinator may seem trivial but it comes in handy. ## bool -Function - Convert the item on the top of the stack to a Boolean value. ### Discussion @@ -384,10 +338,6 @@ Use a Boolean value to select and run one of two quoted programs. T -### Definition - -> [rolldown] [choice] [i] - ### Discussion This is one of the fundamental operations (although it can be defined in @@ -401,50 +351,35 @@ terms of [choice] as above). The more common "if..then..else" construct [select] --------------- - -## • - -See [id](#id). ------------------------------------------------------------------------ ## ccccons -Function - a b c d [...] ccccons --------------------------- [a b c d ...] Do [cons] four times. -### Definition - -> [ccons] [ccons] - ### Crosslinks -[ccons] [cons] [times] +[ccons] +[cons] +[times] -------------------- ## ccons -Function - a b [...] ccons --------------------- [a b ...] Do [cons] two times. -### Definition - -> [cons] [cons] - ### Crosslinks [cons] @@ -455,8 +390,6 @@ Do [cons] two times. ## choice -Function - Use a Boolean value to select one of two items. a b false choice @@ -467,10 +400,6 @@ Use a Boolean value to select one of two items. --------------------- b -### Definition - -> \[[pop]\] \[[popd]\] [branch] - ### Discussion It's a matter of taste whether you implement this in terms of [branch] or @@ -493,14 +422,8 @@ See [xor](#xor). ## clear -Function - Clear everything from the stack. -### Definition - -> [stack] [bool] \[[pop] [stack] [bool]\] [loop] - ### Crosslinks [stack] @@ -553,10 +476,6 @@ Run two programs in parallel, consuming two additional items, and put their resu -------------------------- ... a b -### Definition - -> [cleave] [popdd] - ### Discussion Like [cleave] but consumes an additional item from the stack. @@ -606,11 +525,6 @@ Or even: [GL] [E] over cmp -### Crosslinks - -TODO: link to tree notebooks where this was used. - - ------------------------------------------------------------------------ ## codi @@ -624,10 +538,6 @@ Take a quoted program from the stack, [cons] the next item onto it, then -------------------- b . F a -### Definition - -> [cons] [dip] - ### Discussion This is one of those weirdly specific functions that turns out to be @@ -648,10 +558,6 @@ Combinator This is part of the [make_generator] function. You would not use this combinator directly. -### Definition - -> [codi] [reco] - ### Discussion See [make_generator] and the @@ -668,8 +574,6 @@ as well as ## concat -Function - Concatinate two lists. [a b c] [d e f] concat @@ -739,8 +643,6 @@ expressions, e.g.: ## cons -Function - Given an item and a list, append the item to the list to make a new list. a [...] cons @@ -765,11 +667,6 @@ Combinator Specialist function (that means I forgot what it does and why.) -### Definition - -> [dip] [infrst] - - ------------------------------------------------------------------------ ## dipdd @@ -862,8 +759,6 @@ pending expression (not counting modifications to the dictionary.) ## disenstacken -Function - The `disenstacken` function expects a list on top of the stack and makes that the stack discarding the rest of the stack. @@ -871,10 +766,6 @@ that the stack discarding the rest of the stack. -------------------------------- 6 5 4 -### Definition - -> \[[clear]\] [dip] [reverse] [unstack](#unstack) - ### Discussion Note that the order of the list is not changed, it just looks that way @@ -885,7 +776,6 @@ printed with the top or head on the left. [enstacken] [stack] -[unstack](#unstack) -------------- @@ -899,8 +789,6 @@ See [floordiv](#floordiv). ## divmod -Function - x y divmod ------------------ q r @@ -909,17 +797,10 @@ Function Invariant: `qy + r = x`. -### Definition - -> \[[floordiv]\] \[[mod]\] [clop] - - ------------------------------------------------------------------------ ## down_to_zero -Function - Given a number greater than zero put all the Natural numbers (including zero) less than that onto the stack. @@ -929,10 +810,6 @@ zero) less than that onto the stack. -------------------- 3 2 1 0 -### Definition - -> \[0 \>\] \[[dup] [--]\] [while] - ### Crosslinks [range] @@ -942,8 +819,6 @@ zero) less than that onto the stack. ## drop -Function - Expects an integer and a quote on the stack and returns the quote with n items removed off the top. @@ -953,10 +828,6 @@ items removed off the top. ---------------------- [c d] -### Definition - -> \[[rest]\] [times] - ### Crosslinks [take] @@ -966,18 +837,12 @@ items removed off the top. ## dupdd -Function - [dup] the third item down on the stack. a b c dupdd ----------------- a a b c -### Definition - -> \[[dup]\] [dipd] - ### Crosslinks [dup] @@ -998,10 +863,6 @@ Run a copy of program `F` under the next item down on the stack. ------------------- F a [F] -### Definition - -> [dup] [dipd] - ### Crosslinks [dupdip] @@ -1019,10 +880,6 @@ Apply a function `F` and [dup] the item under it on the stack. ------------------ a F a -### Definition - -> [dupd] [dip] - ### Derivation a [F] dupdip @@ -1045,18 +902,12 @@ A very common and useful combinator. ## dupd -Function - [dup] the second item down on the stack. a b dupd -------------- a a b -### Definition - -> \[[dup]\] [dip] - ### Crosslinks [dup] @@ -1069,8 +920,6 @@ Function ## dup -Function - "Dup"licate the top item on the stack. a dup @@ -1089,8 +938,6 @@ Function ## enstacken -Function - Put the stack onto the stack replacing the contents of the stack. ... a b c enstacken @@ -1098,10 +945,6 @@ Put the stack onto the stack replacing the contents of the stack. [c b a ...] -### Definition - -> [stack] \[[clear]\] [dip] - ### Discussion This is a destructive version of [stack]. See the note under @@ -1110,7 +953,6 @@ This is a destructive version of [stack]. See the note under ### Crosslinks [stack] -[unstack] [disenstacken] @@ -1118,8 +960,6 @@ This is a destructive version of [stack]. See the note under ## eq -Function - Compare the two items on the top of the stack for equality and replace them with a Boolean value. @@ -1156,8 +996,6 @@ See [ne](#ne). ## !- -Function - Not negative. @@ -1171,10 +1009,6 @@ Not negative. true -### Definition - - 0 \>= - ### Discussion Return a Boolean value indicating if a number is greater than or equal to @@ -1185,18 +1019,12 @@ zero. ## first -Function - Replace a list with its first item. [a ...] -------------- a -### Definition - -> [uncons] [pop] - ### Crosslinks [second] @@ -1209,18 +1037,12 @@ Replace a list with its first item. ## first_two -Function - Replace a list with its first two items. [a b ...] first_two ------------------------- a b -### Definition - -> [uncons] [first] - ### Crosslinks [first] @@ -1234,8 +1056,6 @@ Replace a list with its first two items. ## flatten -Function - Given a list of lists, concatinate them. ### Example @@ -1244,10 +1064,6 @@ Given a list of lists, concatinate them. ------------------------------------- [1 2 3 [4] 5 6 7] -### Definition - -> [\<\{\}] \[[concat]\] [step] - ### Discussion Note that only one "level" of lists is flattened. In the example above @@ -1280,8 +1096,6 @@ Note that only one "level" of lists is flattened. In the example above ## floordiv -Function - I don't know why this is called "floor" div, I think it rounds its result down (not towards zero or up.) @@ -1303,8 +1117,6 @@ for Thun gets nailed down. ## floor -Function - Return the largest integer \<= x. ### Discussion @@ -1325,10 +1137,6 @@ Run two quoted programs in parallel and replace them with their results. ---------------------- ... f g -### Definition - -> \[[i]\] [app2] - ### Discussion The basic parallelism combinator, the two programs are run independently. @@ -1344,18 +1152,12 @@ The basic parallelism combinator, the two programs are run independently. ## fourth -Function - Replace a list with its fourth item. [a b c d ...] fourth -------------------------- d -### Definition - -> [rest] [third] - ### Crosslinks [first] @@ -1368,8 +1170,6 @@ Replace a list with its fourth item. ## gcd2 -Function - Compiled GCD function. ### Discussion @@ -1385,15 +1185,9 @@ See [gcd]. ## gcd -Function - Take two integers from the stack and replace them with their Greatest Common Denominator. -### Definition - -> true \[[tuck] [mod] [dup] 0 [>]\] [loop] [pop] - ### Discussion Euclid's Algorithm @@ -1403,8 +1197,6 @@ Euclid's Algorithm ## ge -Function - Greater-than-or-equal-to comparison of two numbers. a b ge @@ -1434,16 +1226,12 @@ Combinator --------------------------------------------------------------------- [if] [then] [rec1 [[if] [then] [rec1] [rec2] genrec] rec2] ifte -### Definition +### Discussion -> \[\[[genrec]\] [ccccons]\] [nullary] [swons] [concat] [ifte] - -(Note that this definition includes the `genrec` symbol itself, it is +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.) - -### Discussion +only self-referential definition. See the [Recursion Combinators notebook](https://joypy.osdn.io/notebooks/Recursion_Combinators.html). @@ -1498,8 +1286,6 @@ Tail recursive functions are those where `R2` is the `i` combinator: ## getitem -Function - Expects an integer and a quote on the stack and returns the item at the nth position in the quote counting from 0. @@ -1509,10 +1295,6 @@ nth position in the quote counting from 0. ------------------------- c -### Definition - -> [drop] [first] - ### Discussion If the number isn't a valid index into the quote `getitem` will cause @@ -1545,8 +1327,6 @@ implementation-dependant.) ## grabN -Function - Expect a number on the top of the stack and [cons] that many items from under it onto a new list. ### Example @@ -1555,16 +1335,10 @@ Expect a number on the top of the stack and [cons] that many items from under it ----------------------- a b [c d e] -### Definition - -> [\<\{\}] \[[cons]\] [times] - ------------------------------------------------------------------------ ## grba -Function - A weird function used in [app2] that does this: ... 1 2 3 4 5 grba @@ -1573,10 +1347,6 @@ A weird function used in [app2] that does this: It grabs the stack under the top item, and substitutes it for the second item down on the stack. -### Definition - -> \[[stack] [popd]\] [dip] - ### Discussion This function "grabs" an item from the stack along with a copy of the stack. @@ -1611,8 +1381,6 @@ See [gt](#gt). ## gt -Function - Greater-than comparison of two numbers. a b gt @@ -1633,8 +1401,6 @@ Greater-than comparison of two numbers. ## help -Function - Accepts a quoted symbol on the top of the stack and prints its documentation. @@ -1665,16 +1431,10 @@ See [sub](#sub). ## hypot -Function - x y hypot --------------------------- sqrt(sqr(x) + sqr(y)) -### Definition - -> \[[sqr]\] [ii] [+] [sqrt] - ### Discussion This is another function that has to wait on the numeric tower. @@ -1688,8 +1448,6 @@ This is another function that has to wait on the numeric tower. ## id -Function - The identity function. ### Discussion @@ -1708,10 +1466,6 @@ If-Then-Else combinator, a common and convenient specialization of [branch]. --------------------------------------- [if] nullary [else] [then] branch -### Definition - -> \[[nullary]\] [dipd] [swap] [branch] - ### Crosslinks [branch] @@ -1731,10 +1485,6 @@ top item, then again with the top item. ------------------ ... Q a Q -### Definition - -> \[[dip]\] [dupdip] [i] - ### Example It's a little tricky to understand how this works so here's an example trace: @@ -1798,10 +1548,6 @@ the list as its stack. Does not affect the stack (below the list.) --------------------------------- c b a Q [z y x ...] swaack -### Definition - -> [swons] [swaack] \[[i]\] [dip] [swaack] - ... [a b c] [F] swons swaack [i] dip swaack ... [[F] a b c] swaack [i] dip swaack @@ -1833,11 +1579,6 @@ Combinator Does [infra] and then extracts the [first] item from the resulting list. -### Definition - -> [infra] [first] - - ------------------------------------------------------------------------ ## inscribe @@ -1860,8 +1601,6 @@ know what you're doing. ## le -Function - Less-Than-or-Equal-to comparison of the two items on the top of the stack, replacing them with a Boolean value. @@ -1897,18 +1636,12 @@ See [ne](#ne). ## <{} -Function - ... a <{} ---------------- ... [] a -### Definition - - [] swap - ### Discussion Tuck an empty list just under the first item on the stack. @@ -1922,19 +1655,12 @@ Tuck an empty list just under the first item on the stack. ## <<{} -Function - ... b a <{} ----------------- ... [] b a -### Definition - - [] rollup - - ### Discussion Tuck an empty list just under the first two items on the stack. @@ -1999,8 +1725,6 @@ Just as [branch] has it's more common and convenient form [ifte], ## lshift -Function - [Logical Left-Shift](https://en.wikipedia.org/wiki/Logical_shift) a n lshift @@ -2015,8 +1739,6 @@ Function ## lt -Function - Less-Than comparison of the two items on the top of the stack, replacing them with a Boolean value. @@ -2038,8 +1760,6 @@ stack, replacing them with a Boolean value. ## make_generator -Function - Given an initial state value and a quoted generator function build a generator quote. @@ -2059,10 +1779,6 @@ And then: --------------------------------------------- 230 231 232 233 234 -### Definition - -> \[[codireco]\] [ccons] - ### Discussion See the ["Using `x` to Generate Values" notebook](https://joypy.osdn.io/notebooks/Generator_Programs.html#an-interesting-variation). @@ -2106,8 +1822,6 @@ parallelism combinator due to the "pure" nature of the language. ## max -Function - Given a list find the maximum. ### Example @@ -2127,8 +1841,6 @@ Given a list find the maximum. ## min -Function - Given a list find the minimum. ### Example @@ -2148,8 +1860,6 @@ Given a list find the minimum. ## mod -Function - Return the remainder of `a` divided by `b`. a b mod @@ -2173,8 +1883,6 @@ See [mod](#mod). ## mul -Function - Multiply two numbers. a b mul @@ -2191,24 +1899,16 @@ Multiply two numbers. ## neg -Function - Invert the sign of a number. a neg ----------- -a -### Definition - -> 0 [swap] [-] - ------------------------------------------------------------------------ ## ne -Function - Not-Equal comparison of the two items on the top of the stack, replacing them with a Boolean value. @@ -2230,8 +1930,6 @@ stack, replacing them with a Boolean value. ## not -Function - Like [bool] but convert the item on the top of the stack to the inverse Boolean value. @@ -2243,10 +1941,6 @@ Boolean value. --------------- true -### Definition - -> [bool] \[true\] \[false\] [branch] - ### Crosslinks [bool] @@ -2256,18 +1950,12 @@ Boolean value. ## nulco -Function - Take the item on the top of the stack and [cons] it onto `[nullary]`. [F] nulco ------------------- [[F] nullary] -### Definition - -> \[[nullary]\] [cons] - ### Discussion Helper function for [\|\|] and [&&]. @@ -2275,7 +1963,7 @@ Helper function for [\|\|] and [&&]. ### Crosslinks [&&] -[\|\|] +[||] -------------------- @@ -2291,10 +1979,6 @@ item of the result on the stack. --------------------- ... a -### Definition - -> \[[stack]\] [dip] [infra] [first] - ### Example ... [P] nullary @@ -2321,8 +2005,6 @@ program.) ## of -Function - Like [getitem] but [swap]s the order of arguments. ### Example @@ -2331,10 +2013,6 @@ Like [getitem] but [swap]s the order of arguments. -------------------- c -### Definition - -> [swap] [getitem] - ### Crosslinks [getitem] @@ -2344,8 +2022,6 @@ Like [getitem] but [swap]s the order of arguments. ## or -Function - Logical bit-wise OR. ### Crosslinks @@ -2358,8 +2034,6 @@ Logical bit-wise OR. ## over -Function - [dup] the second item on the stack `over` the first. a b over @@ -2407,10 +2081,6 @@ rest of the stack.) ------------------------------- 5 7 [12 -2 35 0 5] -### Definition - -> \[[i]\] [map] - ### Discussion A specialization of [map] that runs a list of functions in parallel (if @@ -2453,35 +2123,22 @@ See [succ](#succ). ## pm -Function - Plus or minus. Replace two numbers with their sum and difference. a b pm ----------------- (a+b) (a-b) -### Definition - -> \[+\] \[-\] [clop] - - ------------------------------------------------------------------------ ## popdd -Function - [pop] the third item on the stack. a b c popdd ----------------- b c -### Definition - -> [rolldown] [pop] - ### Crosslinks [pop] @@ -2496,18 +2153,12 @@ Function ## popd -Function - [pop] the second item down on the stack. a b popd -------------- b -### Definition - -> [swap] [pop] - ### Crosslinks [pop] @@ -2522,8 +2173,6 @@ Function ## pop -Function - Pop the top item from the stack and discard it. a pop @@ -2543,16 +2192,10 @@ Pop the top item from the stack and discard it. ## popopdd -Function - a b c d popopdd --------------------- c d -### Definition - -> \[[popop]\] [dipd] - ### Crosslinks [pop] @@ -2567,18 +2210,12 @@ Function ## popopd -Function - [pop] the second and third items from the stack. a b c popopd ------------------ c -### Definition - -> [rollup] [popop] - ### Crosslinks [pop] @@ -2593,17 +2230,11 @@ Function ## popop -Function - [pop] two items from the stack. a b popop --------------- -### Definition - -> [pop] [pop] - ### Crosslinks [pop] @@ -2618,17 +2249,11 @@ Function ## popopop -Function - [pop] three items from the stack. a b c popopop ------------------- -### Definition - -> [pop] [popop] - ### Crosslinks [pop] @@ -2643,8 +2268,6 @@ Function ## pow -Function - Take two numbers `a` and `n` from the stack and raise `a` to the `n`th power. (`n` is on the top of the stack.) @@ -2663,14 +2286,8 @@ power. (`n` is on the top of the stack.) ## pred -Function - Predecessor. Decrement TOS. -### Definition - -> 1 - - ### Crosslinks [succ] @@ -2725,8 +2342,6 @@ Simple and useful specialization of the [genrec] combinator from the ## product -Function - Just as [sum] sums a list of numbers, this function multiplies them together. @@ -2744,14 +2359,8 @@ Or, ## ? -Function - Is the item on the top of the stack "truthy"? -### Definition - -> [dup](#dup) [bool](#bool) - ### Discussion You often want to test the truth value of an item on the stack without @@ -2766,18 +2375,12 @@ consuming the item. ## quoted -Function - "Quote D" Wrap the second item on the stack in a list. a b quoted ---------------- [a] b -### Definition - -> \[[unit]\] [dip] - ### Discussion This comes from the original Joy stuff. @@ -2791,8 +2394,6 @@ This comes from the original Joy stuff. ## range -Function - Expect a number `n` on the stack and replace it with a list: `[(n-1)...0]`. @@ -2806,10 +2407,6 @@ Expect a number `n` on the stack and replace it with a list: -------------- [] -### Definition - -> \[0 \<=\] \[1 - [dup]\] [anamorphism] - ### Discussion If `n` is less than 1 the resulting list is empty. @@ -2823,8 +2420,6 @@ If `n` is less than 1 the resulting list is empty. ## range_to_zero -Function - Take a number `n` from the stack and replace it with a list `[0...n]`. @@ -2834,10 +2429,6 @@ Take a number `n` from the stack and replace it with a list --------------------- [0 1 2 3 4 5] -### Definition - -> [unit] \[[down_to_zero]\] [infra] - ### Discussion Note that the order is reversed compared to [range]. @@ -2852,18 +2443,12 @@ Note that the order is reversed compared to [range]. ## reco -Function - Replace the first item in a list with the item under it. a [b ...] reco -------------------- [a ...] -### Definition - -> [rest] [cons] - ### Crosslinks [codireco] @@ -2888,8 +2473,6 @@ See [mod](#mod). ## remove -Function - Expects an item on the stack and a quote under it and removes that item from the the quote. The item is only removed once. If the list is empty or the item isn't in the list then the list is unchanged. @@ -2907,8 +2490,6 @@ See the ["Remove Function" notebook](https://osdn.net/projects/joypy/scm/git/Thu ## rest -Function - [a ...] rest ------------------ [...] @@ -2923,8 +2504,6 @@ Function ## reverse -Function - Reverse the list on the top of the stack. ### Example @@ -2933,25 +2512,15 @@ Reverse the list on the top of the stack. --------------------- [3 2 1] -### Definition - -> [\<\{\}] [shunt] - ------------------------------------------------------------------------ ## rolldown -Function - a b c rolldown -------------------- b c a -### Definition - -> [swapd] [swap] - ### Crosslinks [rollup] @@ -2975,16 +2544,10 @@ See [rolldown](#rolldown). ## rollup -Function - a b c rollup ------------------ c a b -### Definition - -> [swap] [swapd] - ### Crosslinks [rolldown] @@ -2994,8 +2557,6 @@ Function ## round -Function - Round a number to a given precision in decimal digits. ### Discussion @@ -3008,14 +2569,9 @@ down. ## rrest -Function - [a b ...] rrest --------------------- [...] -### Definition - -> [rest] [rest] ### Crosslinks @@ -3026,8 +2582,6 @@ Function ## rshift -Function - [Logical Right-Shift](https://en.wikipedia.org/wiki/Logical_shift) a n rshift @@ -3042,8 +2596,6 @@ Function ## run -Function - Run a quoted program in a list. ### Example @@ -3052,25 +2604,14 @@ Run a quoted program in a list. ----------------- [3] -### Definition - -> [\<\{\}] [infra] - - ------------------------------------------------------------------------ ## second -Function - [a b ...] second ---------------------- b -### Definition - -> [rest] [first] - ### Crosslinks [first] @@ -3082,8 +2623,6 @@ Function ## select -Function - Use a Boolean value to select one of two items from a sequence. : [a b] false select @@ -3107,8 +2646,6 @@ The sequence can contain more than two items but not fewer. ## sharing -Function - Print redistribution information. ### Discussion @@ -3125,8 +2662,6 @@ printing out the GPL notice. ## shift -Function - Move the top item from one list to another. ### Example @@ -3135,10 +2670,6 @@ Move the top item from one list to another. --------------------------- [a x y z] [b c] -### Definition - -> [uncons] \[[swons]\] [dip] - ### Crosslinks [shunt] @@ -3148,8 +2679,6 @@ Move the top item from one list to another. ## shunt -Function - Like [concat] but [reverse] the top list into the second. ### Example @@ -3158,10 +2687,6 @@ Like [concat] but [reverse] the top list into the second. --------------------------- [f e d a b c] -### Definition - -> \[[swons]\] [step] - ### Discussion This is more efficient than [concat] so prefer it if you don't need to @@ -3178,8 +2703,6 @@ preserve order. ## size -Function - Replace a list with its size. ### Example @@ -3188,10 +2711,6 @@ Replace a list with its size. ------------------------ 3 -### Definition - -> \[[pop] [++]\] [step_zero] - -------------- @@ -3218,8 +2737,6 @@ See [floordiv](#floordiv). ## sort -Function - Given a list return it sorted. ### Example @@ -3233,8 +2750,6 @@ Given a list return it sorted. ## spiral_next -Function - Example code. ### Discussion @@ -3246,8 +2761,6 @@ See the ["Square Spiral Example Joy Code" notebook](https://joypy.osdn.io/notebo ## split_at -Function - Split a list (second on the stack) at the position given by the number on the top of the stack. @@ -3257,10 +2770,6 @@ the top of the stack. -------------------------------- [5 6 7] [4 3 2 1] -### Definition - -> \[[drop]\] \[[take]\] [clop] - ### Discussion Take a list and a number `n` from the stack, take `n` items from the top @@ -3276,8 +2785,6 @@ on the top of the stack. ## split_list -Function - Split a list (second on the stack) at the position given by the number on the top of the stack such that [concat] would reconstruct the original list. @@ -3286,10 +2793,6 @@ list. ---------------------------------- [1 2 3 4] [5 6 7] -### Definition - -> \[[take] [reverse]\] \[[drop]\] [clop] - ### Discussion Compare with [split_at]. This function does extra work to ensure that @@ -3304,19 +2807,12 @@ Compare with [split_at]. This function does extra work to ensure that ## sqr -Function - Square the number on the top of the stack. n sqr ------------ n² -### Definition - -> [dup] [mul] - - ------------------------------------------------------------------------ ## sqrt @@ -3335,8 +2831,6 @@ Another "numeric tower" hatch... ## stackd -Function - Grab the stack under the top item and put it onto the stack. ### Example @@ -3345,27 +2839,17 @@ Grab the stack under the top item and put it onto the stack. ------------------------ ... 1 2 [2 1 ...] 3 -### Definition - -> \[[stack]\] [dip] - ------------------------------------------------------------------------ ## stack -Function - Put the stack onto the stack. ... c b a stack --------------------------- ... c b a [a b c ...] -### Definition - -> \[\] [swaack] [dup] [swaack] [first] - ### Discussion This function forms a pair with [unstack], and together they form the @@ -3373,7 +2857,6 @@ complement to the "destructive" pair [enstacken] and [disenstacken]. ### Crosslinks -[unstack] [enstacken] [disenstacken] @@ -3421,10 +2904,6 @@ Like [step] but with 0 as the initial value. ------------------------- 0 [...] [F] step -### Definition - -> 0 [roll>] [step] - ### Discussion [size] and [sum] can both be defined in terms of this specialization of @@ -3439,8 +2918,6 @@ Like [step] but with 0 as the initial value. ## stuncons -Function - Take the [stack] and [uncons] the top item. ### Example @@ -3449,17 +2926,10 @@ Take the [stack] and [uncons] the top item. -------------------- 1 2 3 3 [2 1] -### Definition - -> [stack] [uncons] - - ------------------------------------------------------------------------ ## stununcons -Function - Take the [stack] and [uncons] the top two items. ### Example @@ -3468,10 +2938,6 @@ Take the [stack] and [uncons] the top two items. ---------------------- 1 2 3 3 2 [1] -### Definition - -> [stack] [uncons] [uncons] - ### Crosslinks [stuncons] @@ -3481,8 +2947,6 @@ Take the [stack] and [uncons] the top two items. ## sub -Function - Subtract the number on the top of the stack from the number below it. a b sub @@ -3498,14 +2962,8 @@ Subtract the number on the top of the stack from the number below it. ## succ -Function - Successor. Increment TOS. -### Definition - -> 1 + - ### Crosslinks [pred] @@ -3525,10 +2983,6 @@ Given a quoted sequence of numbers return the sum. --------------------- 15 -### Definition - -> \[+\] [step_zero] - ### Crosslinks [size] @@ -3538,8 +2992,6 @@ Given a quoted sequence of numbers return the sum. ## swaack -Function - Swap stack. Take a list from the top of the stack, replace the stack with the list, and put the old stack onto it. @@ -3563,18 +3015,12 @@ definition of [infra]. ## swapd -Function - Swap the second and third items on the stack. a b c swapd ----------------- b a c -### Definition - -> \[[swap]\] [dip] - ### Crosslinks [over] @@ -3585,8 +3031,6 @@ Swap the second and third items on the stack. ## swap -Function - Swap the top two items on the stack. a b swap @@ -3602,14 +3046,8 @@ Swap the top two items on the stack. ## swoncat -Function - [concat] two lists, but [swap] the lists first. -### Definition - -> [swap] [concat] - ### Crosslinks [concat] @@ -3619,18 +3057,12 @@ Function ## swons -Function - Like [cons] but [swap] the item and list. [...] a swons ------------------- [a ...] -### Definition - -> [swap] [cons] - ------------------------------------------------------------------------ @@ -3640,10 +3072,6 @@ Combinator A specialization of the [genrec] combinator. -### Definition - -> \[[i]\] [genrec] - ### Discussion Some recursive functions do not need to store additional data or pending @@ -3662,8 +3090,6 @@ See the [Recursion Combinators notebook](https://joypy.osdn.io/notebooks/Recursi ## take -Function - Expects an integer `n` and a list on the stack and replace them with a list with just the top `n` items in reverse order. @@ -3671,11 +3097,6 @@ with just the top `n` items in reverse order. ---------------------- [b a] -### Definition - -> [\<\<\{\}] \[[shift]\] [times] [pop] - - -------------------- ## ternary @@ -3689,10 +3110,6 @@ item of the result on the stack. ------------------------- ... a -### Definition - -> [binary] [popd] - ### Discussion Runs any other quoted function and returns its first result while @@ -3709,16 +3126,10 @@ consuming exactly three items from the stack. ## third -Function - [a b c ...] third ----------------------- c -### Definition - -> [rest] [second] - ### Crosslinks [first] @@ -3748,10 +3159,6 @@ program `n` times. ------------------------------------- w/ n > 1 ... . Q (n-1) [Q] times -### Definition - -> \[\-- dip\] cons \[swap\] infra \[0 \>\] swap while pop : - ### Discussion @@ -3760,13 +3167,13 @@ 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 1 3 [[++] -- dip] • [swap] infra [0 >] swap while pop - 1 3 [[++] -- dip] [swap] • infra [0 >] swap while pop + 1 3 [[++] -- dip] [swap] • infra [0 >] swap while pop dip -- [++] • swap [3 1] swaack [0 >] swap while pop dip [++] -- • [3 1] swaack [0 >] swap while pop dip [++] -- [3 1] • swaack [0 >] swap while pop 1 3 [-- [++] dip] • [0 >] swap while pop - 1 3 [-- [++] dip] [0 >] • swap while pop - 1 3 [0 >] [-- [++] dip] • while pop + 1 3 [-- [++] dip] [0 >] • swap while pop + 1 3 [0 >] [-- [++] dip] • while pop This is a common pattern in Joy. You accept some parameters from the stack which typically include qouted programs and use them to build @@ -3785,8 +3192,6 @@ See [bool](#bool). ## tuck -Function - [dup] the item on the top of the stack under the second item on the stack. @@ -3794,10 +3199,6 @@ stack. -------------- b a b -### Definition - -> [dup] \[[swap]\] [dip] - ### Crosslinks [over] @@ -3816,10 +3217,6 @@ item of the result on the stack. --------------------- ... a -### Definition - -> [nullary] [popd] - ### Discussion Runs any other quoted function and returns its first result while @@ -3836,8 +3233,6 @@ consuming exactly one item from the stack. ## uncons -Function - Removes an item from a list and leaves it on the stack under the rest of the list. You cannot `uncons` an item from an empty list. @@ -3858,8 +3253,6 @@ This is the inverse of [cons]. ## unique -Function - Given a list remove duplicate items. @@ -3867,17 +3260,10 @@ Given a list remove duplicate items. ## unit -Function - a unit ------------ [a] -### Definition - -> \[\] [cons] - - ------------------------------------------------------------------------ ## unquoted @@ -3892,10 +3278,6 @@ Unquote (using [i]) the list that is second on the stack. -------------------------- 1 2 3 4 5 -### Definition - -> \[[i]\] [dip] - ### Crosslinks [unit] @@ -3905,16 +3287,10 @@ Unquote (using [i]) the list that is second on the stack. ## unswons -Function - [a ...] unswons --------------------- [...] a -### Definition - -> [uncons] [swap] - ------------------------------------------------------------------------ @@ -3925,10 +3301,6 @@ Combinator Short-circuiting Boolean OR -### Definition - -> [nulco](#nulco) \[[nullary](#nullary)\] [dip](#dip) \[true\] [branch](#branch) - ### Discussion Accept two quoted programs, run the first and expect a Boolean value, if @@ -3953,8 +3325,6 @@ stack.) ## void -Function - True if the form on TOS is void otherwise False. ### Discussion @@ -3968,8 +3338,6 @@ This represents a binary Boolean logical formula in the arithmetic of the ## warranty -Function - Print warranty information. @@ -3989,10 +3357,6 @@ and runs it [nullary]. --------------------- P -> true F [P] [F] while -### Definition - -> [swap] [nulco] [dupdipd] [concat] [loop] - ### Crosslinks [loop] @@ -4002,8 +3366,6 @@ and runs it [nullary]. ## words -Function - Print all the words in alphabetical order. ### Discussion @@ -4028,10 +3390,6 @@ the stack. ----------- [F] F -### Definition - - dup i - ### Discussion The simplest recursive pattern. @@ -4046,8 +3404,6 @@ as well as ## xor -Function - Logical bit-wise eXclusive OR. ### Crosslinks @@ -4060,8 +3416,6 @@ Logical bit-wise eXclusive OR. ## zip -Function - 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. diff --git a/docs/reference/to_html.py b/docs/reference/to_html.py index 43be074..816b336 100644 --- a/docs/reference/to_html.py +++ b/docs/reference/to_html.py @@ -1,10 +1,68 @@ -import hashlib, re +from collections import defaultdict +import hashlib, re, sys +sys.path.append('../../implementations/Python') +import joy from myhtml import HTML TITLE = 'Thun Function Reference' with open('Function-Reference.md') as f: md = f.read() +with open('../../implementations/defs.txt') as f: + defs = f.read() + +definitions = { + name: body + for name, body in ( + defi.split(None, 1) + for defi in defs.splitlines() + ) + if not name.startswith('_') + } + +def symbols_of(expression): + if isinstance(expression, str): + yield expression + return + if isinstance(expression, tuple) and expression: + yield from symbols_of(expression[0]) + yield from symbols_of(expression[1]) + return + +used_in = { + name: sorted(set(symbols_of(joy.text_to_expression(definitions[name])))) + for name in definitions + } + +used_by = defaultdict(list) +for name in used_in: + for term in used_in[name]: + used_by[term].append(name) +for el in used_by.values(): + el.sort() + + +def def_format(to, name): + try: + defi = definitions[name] + except KeyError: + return + to = to.div(class_='definition') + to.h3('Definition') + to = to.blockquote + start = 0 + for match in re.finditer('[^ [\]]+', defi): + b, e = match.span() + if b != start: + to += defi[start:b] + foo = match.group() + anchor = anchors.get(foo, '') + to.a(foo, href='#' + anchor) + start = e + end = defi[start:] + if end: + to += end + k = re.split('^-+$', md, flags=re.MULTILINE) #k = md.split('------------------------------------------------------------------------\n') @@ -19,7 +77,6 @@ k = [section.splitlines() for section in k] ## s.remove(i) # cannot remove same i twice ##assert not s # one header per section - def anchor_for(name): return 'function_' + ( name @@ -46,6 +103,78 @@ combinators = set( for name in combinators: sections[name].remove('Combinator') +# Crosslinks + +crosslinks = {} +for name, section in sections.items(): + try: + i = section.index('### Crosslinks') + except ValueError: + continue + crosslinks[name] = list(filter(None, section[i + 1:])) + del section[i:] + +discussions = {} +for name, section in sections.items(): + try: + i = section.index('### Discussion') + except ValueError: + continue + discussions[name] = list(filter(None, section[i + 1:])) + del section[i:] + + +def add_crosslinks(to, name): + try: + links = crosslinks[name] + except KeyError: + return + to = to.div(class_='crosslinks') + to.h3('See Also') + first = True + for link in links: + if first: + first = not first + else: + to += ' ' + match = re.match('\[(.+)\].*', link) + if not match: + print('!', link) + continue + link_to = match.group(1) + anchor = anchors[link_to] + to.a(link_to, href='#' + anchor, class_='func_name') + + +def add_discussion(to, name): + try: + discussion = discussions[name] + except KeyError: + return + to = to.div(class_='discussion') + to.h3('Discussion') + to += ('\n'.join(discussion)) + + +def add_backlinks(to, name): + try: + links = used_by[name] + except KeyError: + return + if not links: + return + to = to.div(class_='backlinks') + to.h3('Used By') + first = True + for link_to in links: + if first: + first = not first + else: + to += ' ' + anchor = anchors.get(link_to, '') + to.a(link_to, href='#' + anchor, class_='func_name') + + doc = HTML() with doc.head as h: @@ -65,6 +194,7 @@ with doc.body as b: ul.li.a(name, href='#' + anchor_for(name)) ul += ' ' for name, section in sorted(sections.items()): + b.hr d = b.div anchor_id = anchor_for(name) title = d.h2(name, id=anchor_id, class_='func_name') @@ -73,10 +203,16 @@ with doc.body as b: if name in combinators: d.p.span('combinator', class_='kind') d.pre('\n'.join(section)) - + def_format(d, name) + add_discussion(d, name) + add_crosslinks(d, name) + add_backlinks(d, name) html_string = '' + str(doc) print(html_string, file=open('../html/FuncRef.html', 'w')) #from bs4 import BeautifulSoup #print(BeautifulSoup(html_string, 'html.parser').prettify()) + +##import pprint +##pprint.pprint(crosslinks)