From c3054377a68270f1060dc797b63d6103dd15662e Mon Sep 17 00:00:00 2001 From: sforman Date: Thu, 28 Sep 2023 18:35:54 -0700 Subject: [PATCH] Give it it's own CSS file. It's good enough for now. --- docs/html/FuncRef.html | 1386 ++++++++++++++++------------------ docs/html/css/func_ref.css | 33 + docs/reference/FuncRef.html | 3 + docs/reference/Function-Reference.md | 3 +- docs/reference/HEADER.md | 5 - docs/reference/Makefile | 12 +- 6 files changed, 672 insertions(+), 770 deletions(-) create mode 100644 docs/html/css/func_ref.css delete mode 100644 docs/reference/HEADER.md diff --git a/docs/html/FuncRef.html b/docs/html/FuncRef.html index 9d7ed40..4918cc4 100644 --- a/docs/html/FuncRef.html +++ b/docs/html/FuncRef.html @@ -4,201 +4,46 @@ - Function Reference + Thun Function Reference - + +
-

Function Reference

+

Thun Function Reference

+

Home

Version -10.0.0

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

-

&

-

See and.

+

abs

+

Function

+

Return the absolute value of the argument.

+

Definition

+
+

dup 0 < [] [neg] branch

+
+
+

add

+

Basis Function

+

Add two numbers together: a + b.

-

&&

+

&&

Combinator

Short-circuiting Boolean AND

Accept two quoted programs, run the first and expect a Boolean value, if it’s true pop it and run the second program (which should also return a Boolean value) otherwise pop the second program (leaving false on the stack.)

@@ -364,7 +241,7 @@ [A] [B] && ---------------- false false -

Definition

+

Definition

nulco [nullary [false]] dip branch

Derivation

TODO: this is derived in one of the notebooks I think, look it up and link to it, or copy the content here.

@@ -373,149 +250,8 @@

||

-

*

-

See mul.

-
-

•

-

See id.

-
-

^

-

See xor.

-
-

=

-

See eq.

-
-

!=

-

See ne.

-
-

!-

-

Function

-

Not negative.

-
    n !-
------------ n < 0
-   false
-
-
-   n !-
----------- n >= 0
-   true
-

Definition

-
0 \>=
-

Discussion

-

Return a Boolean value indicating if a number is greater than or equal to zero.

-
-

>

-

See gt.

-
-

>=

-

See ge.

-
-

>>

-

See rshift.

-
-

-

-

See sub.

-
-

–

-

See pred.

-
-

<

-

See lt.

-
-

<=

-

See le.

-
-

<>

-

See ne.

-
-

<{}

-

Function

-
   ... a <{}
-----------------
-   ... [] a
-

Definition

-
[] swap
-

Discussion

-

Tuck an empty list just under the first item on the stack.

- -

<<{}

-
-

<<

-

See lshift.

-
-

<<{}

-

Function

-
   ... b a <{}
------------------
-   ... [] b a
-

Definition

-
[] rollup
-

Discussion

-

Tuck an empty list just under the first two items on the stack.

- -

<{}

-
-

%

-

See mod.

-
-

+

-

See add.

-
-

++

-

See succ.

-
-

?

-

Function

-

Is the item on the top of the stack “truthy”?

-

Definition

-
-

dup bool

-
-

Discussion

-

You often want to test the truth value of an item on the stack without consuming the item.

- -

bool

-
-

/

-

See floordiv.

-
-

//

-

See floordiv.

-
-

/floor

-

See floordiv.

-
-

||

-

Combinator

-

Short-circuiting Boolean OR

-

Definition

-
-

nulco [nullary] dip [true] branch

-
-

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

&&

-
-

abs

-

Function

-

Return the absolute value of the argument.

-

Definition

-
-

dup 0 < [] [neg] branch

-
-
-

add

-

Basis Function

-

Add two numbers together: a + b.

+

&

+

See and.

anamorphism

Combinator

@@ -523,7 +259,7 @@ 
           [P] [G] anamorphism
 -----------------------------------------
    [P] [pop []] [G] [dip swons] genrec
-

Definition

+

Definition

[pop []] swap [dip swons] genrec

@@ -532,13 +268,13 @@

[0 <=] [-- dup] anamorphism

-

Discussion

+

Discussion

See the Recursion Combinators notebook.

and

Basis Function

Logical bit-wise AND.

- +

or xor

app1

@@ -549,13 +285,13 @@ --------------------------------- ... [x ...] [Q] infra first

This is the same effect as the unary combinator.

-

Definition

+

Definition

nullary popd

-

Discussion

+

Discussion

Just a specialization of nullary really. Its parallelizable cousins are more useful.

- +

app2 app3 appN unary

app2

@@ -565,14 +301,14 @@ ----------------------------------- ... [y ...] [Q] . infra first [x ...] [Q] infra first -

Definition

+

Definition

[grba swap grba swap] dip [infrst] cons ii

-

Discussion

+

Discussion

Unlike app1, which is essentially an alias for unary, this function is not the same as binary. Instead of running one program using exactly two items from the stack and pushing one result (as binary does) this function takes two items from the stack and runs the program twice, separately for each of the items, then puts both results onto the stack.

This is not currently implemented as parallel processes but it can (and should) be done.

- +

app1 app3 appN unary

app3

@@ -583,13 +319,13 @@ ... [z ...] [Q] . infra first [y ...] [Q] infra first [x ...] [Q] infra first -

Definition

+

Definition

3 appN

-

Discussion

+

Discussion

See app2.

- +

app1 app2 appN unary

appN

@@ -602,65 +338,68 @@ [x2 ...] [Q] infra first [x1 ...] [Q] infra first [x0 ...] [Q] infra first -

Definition

+

Definition

[grabN] codi map disenstacken

-

Discussion

+

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.

- +

app1 app2 app3 unary

+

*

+

See mul.

+

at

See 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

+

Definition

[sum] [size] cleave /

-

Discussion

+

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.

-

b

-

Combinator

-

Run two quoted programs

-
   [P] [Q] b
----------------
-      P Q
-

Definition

-
-

[i] dip i

-
-

Discussion

-

This combinator may seem trivial but it comes in handy.

- -

dupdip ii

-

binary

Combinator

Run a quoted program using exactly two stack values and leave the first item of the result on the stack.

   ... y x [P] binary
 -----------------------
         ... a
-

Definition

+

Definition

unary popd

-

Discussion

+

Discussion

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

- +

nullary ternary unary

+

b

+

Combinator

+

Run two quoted programs

+
   [P] [Q] b
+---------------
+      P Q
+

Definition

+
+

[i] dip i

+
+

Discussion

+

This combinator may seem trivial but it comes in handy.

+ +

dupdip ii

+

bool

Basis Function

Convert the item on the top of the stack to a Boolean value.

-

Discussion

+

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.

- +

not

branch

@@ -673,26 +412,29 @@ true [F] [T] branch ------------------------- T -

Definition

+

Definition

rolldown choice i

-

Discussion

+

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.

- +

choice ifte select

+

•

+

See id.

+

ccccons

Function

   a b c d [...] ccccons
 ---------------------------
        [a b c d ...]

Do cons four times.

-

Definition

+

Definition

ccons ccons

- +

ccons cons times

ccons

@@ -701,11 +443,11 @@ --------------------- [a b ...]

Do cons two times.

-

Definition

+

Definition

cons cons

- +

cons ccons

choice

@@ -718,23 +460,26 @@ a b true choice --------------------- b -

Definition

+

Definition

[pop] [popd] branch

-

Discussion

+

Discussion

It’s a matter of taste whether you implement this in terms of branch or the other way around.

- +

branch select

+

^

+

See xor.

+

clear

Basis Function

Clear everything from the stack.

-

Definition

+

Definition

stack bool [pop stack bool] loop

- +

stack swaack

cleave

@@ -751,9 +496,9 @@ 
   1 2 3 [+] [-] cleave
 --------------------------
          1 2 5 -1
-

Discussion

+

Discussion

One of a handful of useful parallel combinators.

- +

clop fork map

clop

@@ -762,16 +507,16 @@ 
   ... x y [A] [B] clop
 --------------------------
         ... a b
-

Definition

+

Definition

cleave popdd

-

Discussion

+

Discussion

Like cleave but consumes an additional item from the stack.

   1 2 3 4 [+] [-] clop
 --------------------------
          1 2 7 -1
- +

cleave fork map

cmp

@@ -788,14 +533,14 @@ a b [G] [E] [L] cmp ------------------------- a < b L -

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

+

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

TODO: link to tree notebooks where this was used.

codi

@@ -804,25 +549,25 @@ 
   a b [F] . codi
 --------------------
          b . F a
-

Definition

+

Definition

cons dip

-

Discussion

+

Discussion

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

- +

appN codireco

codireco

Combinator

This is part of the make_generator function. You would not use this combinator directly.

-

Definition

+

Definition

codi reco

-

Discussion

+

Discussion

See make_generator and the “Using x to Generate Values” notebook as well as Recursion Theory and Joy by Manfred von Thun.

- +

make_generator

concat

@@ -831,7 +576,7 @@ 
   [a b c] [d e f] concat
 ----------------------------
        [a b c d e f]
- +

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

cond

@@ -845,12 +590,12 @@ [Default] ] cond -

Discussion

+

Discussion

It works by rewriting into a chain of nested ifte expressions, e.g.:

      [[[B0] T0] [[B1] T1] [D]] cond
 -----------------------------------------
    [B0] [T0] [[B1] [T1] [D] ifte] ifte
- +

ifte

cons

@@ -859,66 +604,66 @@ cond 
   a [...] cons
 ------------------
      [a ...]
-

Discussion

+

Discussion

Cons is a venerable old function from Lisp. Its inverse operation is uncons.

- +

uncons

dinfrirst

Combinator

Specialist function (that means I forgot what it does and why.)

-

Definition

+

Definition

dip infrst

-

dip

-

Basis Combinator

-

The dip combinator expects a quoted program on the stack and below it some item, it hoists the item into the expression and runs the program on the rest of the stack.

-
   ... x [Q] . dip
----------------------
-         ... . Q x
-

Discussion

-

This along with infra are enough to update any datastructure. See the “Traversing Datastructures with Zippers” notebook.

-

Note that the item that was on the top of the stack (x in the example above) will not be treated specially by the interpreter when it is reached again. This is something of a footgun. My advice is to avoid putting bare unquoted symbols onto the stack, but then you can’t use symbols as “atoms” and also use dip and infra to operate on compound datastructures with atoms in them. This is a kind of side-effect of the Continuation-Passing Style. The dip combinator could “set aside” the item and replace it after running Q but that means that there is an “extra space” where the item resides while Q runs. One of the nice things about CPS is that the whole state is recorded in the stack and pending expression (not counting modifications to the dictionary.)

- -

dipd dipdd dupdip dupdipd infra

-
-

dipd

-

Combinator

-

Like dip but expects two items.

-
   ... y x [Q] . dipd
--------------------------
-           ... . Q y x
-

Discussion

-

See dip.

- -

dip dipdd dupdip dupdipd infra

-

dipdd

Combinator

Like dip but expects three items. :

   ... z y x [Q] . dip
 -----------------------------
              ... . Q z y x
-

Discussion

+

Discussion

See dip.

- +

dip dipd dupdip dupdipd infra

+

dipd

+

Combinator

+

Like dip but expects two items.

+
   ... y x [Q] . dipd
+-------------------------
+           ... . Q y x
+

Discussion

+

See dip.

+ +

dip dipdd dupdip dupdipd infra

+
+

dip

+

Basis Combinator

+

The dip combinator expects a quoted program on the stack and below it some item, it hoists the item into the expression and runs the program on the rest of the stack.

+
   ... x [Q] . dip
+---------------------
+         ... . Q x
+

Discussion

+

This along with infra are enough to update any datastructure. See the “Traversing Datastructures with Zippers” notebook.

+

Note that the item that was on the top of the stack (x in the example above) will not be treated specially by the interpreter when it is reached again. This is something of a footgun. My advice is to avoid putting bare unquoted symbols onto the stack, but then you can’t use symbols as “atoms” and also use dip and infra to operate on compound datastructures with atoms in them. This is a kind of side-effect of the Continuation-Passing Style. The dip combinator could “set aside” the item and replace it after running Q but that means that there is an “extra space” where the item resides while Q runs. One of the nice things about CPS is that the whole state is recorded in the stack and pending expression (not counting modifications to the dictionary.)

+ +

dipd dipdd 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.

   1 2 3 [4 5 6] disenstacken
 --------------------------------
             6 5 4
-

Definition

+

Definition

[clear] dip reverse unstack

-

Discussion

+

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.

- +

enstacken stack unstack

div

@@ -931,7 +676,7 @@ cond q r (x/y) (x%y)

Invariant: qy + r = x.

-

Definition

+

Definition

[floordiv] [mod] clop

@@ -943,11 +688,11 @@ cond 
   3 down_to_zero
 --------------------
       3 2 1 0
-

Definition

+

Definition

-

[0 >] [dup –] while

+

[0 >] [dup –] while

- +

range

drop

@@ -957,55 +702,46 @@ cond 
   [a b c d] 2 drop
 ----------------------
        [c d]
-

Definition

+

Definition

[rest] times

- +

take

-

dup

-

Basis Function

-

“Dup”licate the top item on the stack.

-
   a dup
------------
-    a a
- -

dupd dupdd dupdip dupdipd

-
-

dupd

-

Function

-

dup the second item down on the stack.

-
   a b dupd
---------------
-    a a b
-

Definition

-
-

[dup] dip

-
- -

dup dupdd dupdip dupdipd

-

dupdd

Function

dup the third item down on the stack.

   a b c dupdd
 -----------------
      a a b c
-

Definition

+

Definition

[dup] dipd

- +

dup dupd dupdip dupdipd

+

dupdipd

+

Combinator

+

Run a copy of program F under the next item down on the stack.

+
   a [F] dupdipd
+-------------------
+      F a [F]
+

Definition

+
+

dup dipd

+
+ +

dupdip

+

dupdip

Combinator

Apply a function F and dup the item under it on the stack.

   a [F] dupdip
 ------------------
       a F a
-

Definition

+

Definition

dupd dip

@@ -1016,23 +752,32 @@ a [F] [dup] dip dip a dup [F] dip a a [F] dip a F a -

Discussion

+

Discussion

A very common and useful combinator.

- +

dupdipd

-

dupdipd

-

Combinator

-

Run a copy of program F under the next item down on the stack.

-
   a [F] dupdipd
--------------------
-      F a [F]
-

Definition

+

dupd

+

Function

+

dup the second item down on the stack.

+
   a b dupd
+--------------
+    a a b
+

Definition

-

dup dipd

+

[dup] dip

- -

dupdip

+ +

dup dupdd dupdip dupdipd

+
+

dup

+

Basis Function

+

“Dup”licate the top item on the stack.

+
   a dup
+-----------
+    a a
+ +

dupd dupdd dupdip dupdipd

enstacken

Function

@@ -1040,13 +785,13 @@ a F a 
   ... a b c enstacken
 -------------------------
        [c b a ...]
-

Definition

+

Definition

stack [clear] dip

-

Discussion

+

Discussion

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

- +

stack [unstack] disenstacken

eq

@@ -1056,20 +801,42 @@ a F a ------------- Boolean (a = b) - +

cmp ge gt le lt ne

+

=

+

See eq.

+
+

!=

+

See ne.

+
+

!-

+

Function

+

Not negative.

+
    n !-
+----------- n < 0
+   false
+
+
+   n !-
+---------- n >= 0
+   true
+

Definition

+
0 \>=
+

Discussion

+

Return a Boolean value indicating if a number is greater than or equal to zero.

+

first

Function

Replace a list with its first item.

   [a ...]
 --------------
       a
-

Definition

+

Definition

uncons pop

- +

second third fourth rest

first_two

@@ -1078,11 +845,11 @@ a F a 
   [a b ...] first_two
 -------------------------
            a b
-

Definition

+

Definition

uncons first

- +

first second third fourth rest

flatten

@@ -1092,45 +859,45 @@ a F a 
   [[1 2] [3 [4] 5] [6 7]] flatten
 -------------------------------------
           [1 2 3 [4] 5 6 7]
-

Definition

+

Definition

-

<{} [concat] step

+

<{} [concat] step

-

Discussion

+

Discussion

Note that only one “level” of lists is flattened. In the example above [4] is not unquoted.

- +

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

-

floor

-

Basis 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

Basis Function

I don’t know why this is called “floor” div, I think it rounds its result down (not towards zero or up.)

   a b floordiv
 ------------------
       (a/b)
-

Discussion

+

Discussion

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

- +

divmod

+

floor

+

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

+

fork

Combinator

Run two quoted programs in parallel and replace them with their results.

   ... [F] [G] fork
 ----------------------
        ... f g
-

Definition

+

Definition

[i] app2

-

Discussion

+

Discussion

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

- +

cleave clop map

fourth

@@ -1139,31 +906,31 @@ a F a 
   [a b c d ...] fourth
 --------------------------
           d
-

Definition

+

Definition

rest third

- +

first second third rest

+

gcd2

+

Function

+

Compiled GCD function.

+

Discussion

+

See gcd.

+ +

gcd

+

gcd

Function

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

-

Definition

+

Definition

-

true [tuck mod dup 0 >] loop pop

+

true [tuck mod dup 0 >] loop pop

-

Discussion

+

Discussion

Euclid’s Algorithm

-

gcd2

-

Function

-

Compiled GCD function.

-

Discussion

-

See gcd.

- -

gcd

-

ge

Basis Function

Greater-than-or-equal-to comparison of two numbers.

@@ -1171,7 +938,7 @@ a F a -------------- Boolean (a >= b) - +

cmp eq gt le lt ne

genrec

@@ -1180,12 +947,12 @@ a F a 
                      [if] [then] [rec1] [rec2] genrec
 ---------------------------------------------------------------------
    [if] [then] [rec1 [[if] [then] [rec1] [rec2] genrec] rec2] ifte
-

Definition

+

Definition

[[genrec] ccccons] nullary swons concat ifte

(Note that this definition includes the genrec symbol itself, it is self-referential. This is possible because the definition machinery does not check that symbols in defs are in the dictionary. genrec is the only self-referential definition.)

-

Discussion

+

Discussion

See the Recursion Combinators notebook.

From “Recursion Theory and Joy” by Manfred von Thun:

@@ -1203,7 +970,7 @@ a F a 
P == [I] [T] [R] tailrec
   == [I] [T] [R [P] i] ifte
   == [I] [T] [R P] ifte
- +

anamorphism tailrec x

getitem

@@ -1213,13 +980,13 @@ a F a 
   [a b c d] 2 getitem
 -------------------------
         c
-

Definition

+

Definition

drop first

-

Discussion

+

Discussion

If the number isn’t a valid index into the quote getitem will cause some sort of problem (the exact nature of which is implementation-dependant.)

- +

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

grabN

@@ -1229,9 +996,9 @@ a F a 
   a b c d e 3 grabN
 -----------------------
       a b [c d e]
-

Definition

+

Definition

-

<{} [cons] times

+

<{} [cons] times

grba

@@ -1241,15 +1008,24 @@ a F a ------------------------------- ... 1 2 3 [4 3 2 1 ...] 5

It grabs the stack under the top item, and substitutes it for the second item down on the stack.

-

Definition

+

Definition

[stack popd] dip

-

Discussion

+

Discussion

This function “grabs” an item from the stack along with a copy of the stack. It’s part of the app2 definition.

- +

app2

+

>=

+

See ge.

+
+

>>

+

See rshift.

+
+

>

+

See gt.

+

gt

Basis Function

Greater-than comparison of two numbers.

@@ -1257,7 +1033,7 @@ a F a -------------- Boolean (a > b) - +

cmp eq ge le lt ne

help

@@ -1265,36 +1041,33 @@ a F a

Accepts a quoted symbol on the top of the stack and prints its documentation.

   [foo] help
 ----------------
-

Discussion

+

Discussion

Technically this is equivalent to pop, but it will only work if the item on the top of the stack is a quoted symbol.

+

–

+

See pred.

+
+

-

+

See sub.

+

hypot

Function

         x y hypot
 ---------------------------
    sqrt(sqr(x) + sqr(y))
-

Definition

+

Definition

[sqr] ii + sqrt

-

Discussion

+

Discussion

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

- +

sqrt

-

i

-

Basis Combinator

-

Append a quoted expression onto the pending expression.

-
   [Q] . i
--------------
-       . Q
-

Discussion

-

This is a fundamental combinator. It is used in all kinds of places. For example, the x combinator can be defined as dup i.

-

id

Basis Function

The identity function.

-

Discussion

+

Discussion

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

ifte

@@ -1303,11 +1076,11 @@ a F a 
        [if] [then] [else] ifte
 ---------------------------------------
    [if] nullary [else] [then] branch
-

Definition

+

Definition

[nullary] dipd swap branch

- +

branch loop while

ii

@@ -1316,7 +1089,7 @@ a F a 
... a [Q] ii
 ------------------
  ... Q a Q
-

Definition

+

Definition

[dip] dupdip i

@@ -1331,7 +1104,7 @@ a F a 1 2 4 4 [++] • i 1 2 4 4 • ++ 1 2 4 5 • -

Discussion

+

Discussion

In some cases (like the example above) this is the same effect as using app2 but most of the time it’s not:

   1 2 3 4 [+] ii
 --------------------
@@ -1340,28 +1113,45 @@ a F a
1 2 3 4 [+] app2 ---------------------- 1 2 5 6 - +

app2 b

+

i

+

Basis Combinator

+

Append a quoted expression onto the pending expression.

+
   [Q] . i
+-------------
+       . Q
+

Discussion

+

This is a fundamental combinator. It is used in all kinds of places. For example, the x combinator can be defined as dup i.

+

infra

Combinator

Accept a quoted program and a list on the stack and run the program with the list as its stack. Does not affect the stack (below the list.)

   ... x y z [a b c] [Q] infra
 ---------------------------------
     c b a Q [z y x ...] swaack
-

Definition

+

Definition

swons swaack [i] dip swaack

-

Discussion

+
... [a b c] [F] swons swaack [i] dip swaack
+... [[F] a b c]       swaack [i] dip swaack
+
+c b a [F]   [...] [i] dip swaack
+c b a [F] i [...]         swaack
+c b a  F    [...]         swaack
+d e         [...]         swaack
+... [e d]
+

Discussion

This is one of the more useful combinators. It allows a quoted expression to serve as a stack for a program, effectively running it in a kind of “pocket universe”. If the list represents a datastructure then infra lets you work on its internal structure.

- +

swaack

infrst

Combinator

Does infra and then extracts the first item from the resulting list.

-

Definition

+

Definition

infra first

@@ -1370,7 +1160,7 @@ a F a

Create a new Joy function definition in the Joy dictionary. A definition is given as a quote with a name followed by a Joy expression.

Example

[sqr dup mul] inscribe
-

Discussion

+

Discussion

This is the only function that modifies the dictionary. It’s provided as a convenience, for tinkering with new definitions before entering them into the defs.txt file. It can be abused, which you should avoid unless you know what you’re doing.

le

@@ -1380,9 +1170,45 @@ a F a ------------- Boolean (a <= b) - +

cmp eq ge gt lt ne

+

<=

+

See le.

+
+

<>

+

See ne.

+
+

<{}

+

Function

+
   ... a <{}
+----------------
+   ... [] a
+

Definition

+
[] swap
+

Discussion

+

Tuck an empty list just under the first item on the stack.

+ +

<<{}

+
+

<<{}

+

Function

+
   ... b a <{}
+-----------------
+   ... [] b a
+

Definition

+
[] rollup
+

Discussion

+

Tuck an empty list just under the first two items on the stack.

+ +

<{}

+
+

<<

+

See lshift.

+
+

<

+

See lt.

+

loop

Basis Combinator

Expect a quoted program Q and a Boolean value on the stack. If the value is false discard the quoted program, otherwise run a copy of Q and loop again.

@@ -1393,13 +1219,13 @@ a F a true [Q] . loop -------------------------- . Q [Q] loop -

Discussion

+

Discussion

This, along with branch and fork, is one of the four main combinators of all programming. The fourth, sequence, is implied by juxtaposition. That is to say, in Joy F G is like G(F(...)) in a language bassed on function application. Or again, to quote the Joy Wikipedia entry,

In Joy, the meaning function is a homomorphism from the syntactic monoid onto the semantic monoid. That is, the syntactic relation of concatenation of symbols maps directly onto the semantic relation of composition of functions.

Anyway, branch, fork, amd loop are the fundamental combinators in Joy. Just as branch has it’s more common and convenient form ifte, loop has while.

- +

branch fork while

lshift

@@ -1408,7 +1234,7 @@ a F a 
   a n lshift
 ----------------
      (a×2ⁿ)
- +

rshift

lt

@@ -1418,7 +1244,7 @@ a F a ------------- Boolean (a < b) - +

cmp eq ge gt le ne

make_generator

@@ -1435,13 +1261,13 @@ a F a 
   [230 [dup ++] codireco] 5 [x] times pop
 ---------------------------------------------
              230 231 232 233 234
-

Definition

+

Definition

[codireco] ccons

-

Discussion

+

Discussion

See the “Using x to Generate Values” notebook.

- +

codireco

map

@@ -1451,9 +1277,9 @@ a F a 
   5 [1 2 3] [++ *] map
 --------------------------
        5 [10 15 20]
-

Discussion

+

Discussion

This is a common operation in many languages. In Joy it can be a parallelism combinator due to the “pure” nature of the language.

- +

app1 app2 app3 appN fork

max

@@ -1463,7 +1289,7 @@ a F a 
   [1 2 3 4] max
 -------------------
          4
- +

min size sum

min

@@ -1473,7 +1299,7 @@ a F a 
   [1 2 3 4] min
 -------------------
          1
- +

max size sum

mod

@@ -1482,7 +1308,7 @@ a F a 
   a b mod
 -------------
     (a%b)
- +

divmod mul

modulus

@@ -1494,30 +1320,30 @@ a F a 
   a b mul
 -------------
     (a×b)
- +

div product

-

ne

-

Basis Function

-

Not-Equal comparison of the two items on the top of the stack, replacing them with a Boolean value.

-
   a b ne
--------------
-   Boolean
-   (a = b)
- -

cmp eq ge gt le lt

-

neg

Function

Invert the sign of a number.

   a neg
 -----------
     -a
-

Definition

+

Definition

-

0 swap -

+

0 swap -

+

ne

+

Basis Function

+

Not-Equal comparison of the two items on the top of the stack, replacing them with a Boolean value.

+
   a b ne
+-------------
+   Boolean
+   (a = b)
+ +

cmp eq ge gt le lt

+

not

Function

Like bool but convert the item on the top of the stack to the inverse Boolean value.

@@ -1528,11 +1354,11 @@ a F a false not --------------- true -

Definition

+

Definition

bool [true] [false] branch

- +

bool

nulco

@@ -1541,14 +1367,14 @@ a F a 
     [F] nulco
 -------------------
    [[F] nullary]
-

Definition

+

Definition

[nullary] cons

-

Discussion

-

Helper function for || and &&.

- -

&& ||

+

Discussion

+

Helper function for || and &&.

+ +

&& ||

nullary

Combinator

@@ -1556,7 +1382,7 @@ a F a 
   ... [P] nullary
 ---------------------
         ... a
-

Definition

+

Definition

[stack] dip infra first

@@ -1567,9 +1393,9 @@ a F a ... [...] [P] infra first ... [a ...] first ... a -

Discussion

+

Discussion

A very useful function that runs any other quoted function and returns it’s first result without disturbing the stack (under the quoted program.)

- +

unary binary ternary

of

@@ -1579,17 +1405,17 @@ a F a 
   2 [a b c d] of
 --------------------
          c
-

Definition

+

Definition

swap getitem

- +

getitem

or

Basis Function

Logical bit-wise OR.

- +

and xor

over

@@ -1598,7 +1424,7 @@ a F a 
   a b over
 --------------
     a b a
-

Definition

+

Definition

There are many many ways to define this function.

swap tuck

@@ -1616,9 +1442,9 @@ a F a

unit dupdipd first

And so on…

-

Discussion

+

Discussion

A fine old word from Forth.

- +

tuck

pam

@@ -1628,36 +1454,50 @@ a F a 
   5 7 [[+][-][*][/][%]] pam
 -------------------------------
       5 7 [12 -2 35 0 5]
-

Definition

+

Definition

[i] map

-

Discussion

+

Discussion

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

- +

map

+

%

+

See mod.

+

pick

See getitem.

+

+

+

See add.

+
+

++

+

See succ.

+

pm

Function

Plus or minus. Replace two numbers with their sum and difference.

      a b pm
 -----------------
    (a+b) (a-b)
-

Definition

+

Definition

[+] [-] clop

-

pop

-

Basis Function

-

Pop the top item from the stack and discard it.

-
   a pop
------------
- -

popd popdd popop popopd popopdd popopop

+

popdd

+

Function

+

pop the third item on the stack.

+
   a b c popdd
+-----------------
+       b c
+

Definition

+
+

rolldown pop

+
+ +

pop popd popop popopd popopdd popopop

popd

Function

@@ -1665,37 +1505,32 @@ a F a 
   a b popd
 --------------
       b
-

Definition

+

Definition

swap pop

- +

pop popdd popop popopd popopdd popopop

-

popdd

-

Function

-

pop the third item on the stack.

-
   a b c popdd
------------------
-       b c
-

Definition

-
-

rolldown pop

-
- -

pop popd popop popopd popopdd popopop

+

pop

+

Basis Function

+

Pop the top item from the stack and discard it.

+
   a pop
+-----------
+ +

popd popdd popop popopd popopdd popopop

-

popop

+

popopdd

Function

-

pop two items from the stack.

-
   a b popop
----------------
-

Definition

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

Definition

-

pop pop

+

[popop] dipd

- -

pop popd popdd popopd popopdd popopop

+ +

pop popd popdd popop popopd popopop

popopd

Function

@@ -1703,40 +1538,40 @@ a F a 
   a b c popopd
 ------------------
         c
-

Definition

+

Definition

rollup popop

- +

pop popd popdd popop popopdd popopop

-

popopdd

+

popop

Function

-
   a b c d popopdd
----------------------
-        c d
-

Definition

+

pop two items from the stack.

+
   a b popop
+---------------
+

Definition

-

[popop] dipd

+

pop pop

- -

pop popd popdd popop popopd popopop

+ +

pop popd popdd popopd popopdd popopop

popopop

Function

pop three items from the stack.

   a b c popopop
 -------------------
-

Definition

+

Definition

pop popop

- +

pop popd popdd popop popopd popopdd

pow

Basis Function

-

Take two numbers a and b from the stack and raise a to the nth power. (b is on the top of the stack.)

+

Take two numbers a and n from the stack and raise a to the nth power. (n is on the top of the stack.)

   a n pow
 -------------
     (aⁿ)
@@ -1748,11 +1583,11 @@ a F a

pred

Function

Predecessor. Decrement TOS.

-

Definition

+

Definition

1 -

- +

succ

primrec

@@ -1774,15 +1609,15 @@ a F a n [Base] [Recur] primrec ------------------------------------------ n > 0 n (n-1) [Base] [Recur] primrec Recur -

Discussion

+

Discussion

Simple and useful specialization of the genrec combinator from the original Joy system.

- +

genrec tailrec

product

Function

Just as sum sums a list of numbers, this function multiplies them together.

-

Definition

+

Definition

1 swap [mul] step

@@ -1791,19 +1626,31 @@ a F a

[1] [mul] primrec

+

?

+

Function

+

Is the item on the top of the stack “truthy”?

+

Definition

+
+

dup bool

+
+

Discussion

+

You often want to test the truth value of an item on the stack without consuming the item.

+ +

bool

+

quoted

Function

“Quote D” Wrap the second item on the stack in a list.

   a b quoted
 ----------------
      [a] b
-

Definition

+

Definition

[unit] dip

-

Discussion

+

Discussion

This comes from the original Joy stuff.

- +

unit

range

@@ -1817,13 +1664,13 @@ a F a -5 range -------------- [] -

Definition

+

Definition

[0 <=] [1 - dup] anamorphism

-

Discussion

+

Discussion

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

- +

range_to_zero

range_to_zero

@@ -1833,13 +1680,13 @@ a F a 
   5 range_to_zero
 ---------------------
     [0 1 2 3 4 5]
-

Definition

+

Definition

unit [down_to_zero] infra

-

Discussion

+

Discussion

Note that the order is reversed compared to range.

- +

down_to_zero range

reco

@@ -1848,17 +1695,17 @@ a F a 
   a [b ...] reco
 --------------------
      [a ...]
-

Definition

+

Definition

rest cons

- +

codireco make_generator

-

rem

+

remainder

See mod.

-

remainder

+

rem

See mod.

remove

@@ -1867,7 +1714,7 @@ a F a 
   [1 2 3 1] 1 remove
 ------------------------
         [2 3 1]
-

Definition

+

Definition

See the “Remove Function” notebook.

rest

@@ -1875,7 +1722,7 @@ a F a 
   [a ...] rest
 ------------------
       [...]
- +

first uncons

reverse

@@ -1885,9 +1732,9 @@ a F a 
   [1 2 3] reverse
 ---------------------
        [3 2 1]
-

Definition

+

Definition

-

<{} shunt

+

<{} shunt

rolldown

@@ -1895,35 +1742,35 @@ a F a 
   a b c rolldown
 --------------------
        b c a
-

Definition

+

Definition

swapd swap

- +

rollup

+

roll>

+

See rollup.

+
+

roll<

+

See rolldown.

+

rollup

Function

   a b c rollup
 ------------------
       c a b
-

Definition

+

Definition

swap swapd

- +

rolldown

-

roll>

-

See rollup.

-
-

roll<

-

See rolldown.

-

round

Function

Round a number to a given precision in decimal digits.

-

Discussion

+

Discussion

Another one that won’t make sense until the “numeric tower” is nailed down.

rrest

@@ -1931,11 +1778,11 @@ a F a 
   [a b ...] rrest
 ---------------------
         [...]
-

Definition

+

Definition

rest rest

- +

rest

rshift

@@ -1944,7 +1791,7 @@ a F a 
   a n rshift
 ----------------
      (a∕2ⁿ)
- +

lshift

run

@@ -1954,9 +1801,9 @@ a F a 
   [1 2 +] run
 -----------------
        [3]
-

Definition

+

Definition

-

<{} infra

+

<{} infra

second

@@ -1964,11 +1811,11 @@ a F a 
   [a b ...] second
 ----------------------
           b
-

Definition

+

Definition

rest first

- +

first third fourth

select

@@ -1981,17 +1828,17 @@ a F a [a b] true select ----------------------- b -

Discussion

+

Discussion

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

- +

choice

sharing

Function

Print redistribution information.

-

Discussion

+

Discussion

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

- +

warranty

shift

@@ -2001,11 +1848,11 @@ a F a 
   [x y z] [a b c] shift
 ---------------------------
       [a x y z] [b c]
-

Definition

+

Definition

uncons [swons] dip

- +

shunt

shunt

@@ -2015,13 +1862,13 @@ a F a 
   [a b c] [d e f] shunt
 ---------------------------
        [f e d a b c]
-

Definition

+

Definition

[swons] step

-

Discussion

+

Discussion

This is more efficient than concat so prefer it if you don’t need to preserve order.

- +

concat reverse shift

size

@@ -2031,11 +1878,20 @@ a F a 
   [23 [cats] 4] size
 ------------------------
            3
-

Definition

+

Definition

[pop ++] step_zero

+

/floor

+

See floordiv.

+
+

/

+

See floordiv.

+
+

//

+

See floordiv.

+

sort

Function

Given a list return it sorted.

@@ -2047,7 +1903,7 @@ a F a

spiral_next

Function

Example code.

-

Discussion

+

Discussion

See the “Square Spiral Example Joy Code” notebook.

split_at

@@ -2057,13 +1913,13 @@ a F a 
   [1 2 3 4 5 6 7] 4 split_at
 --------------------------------
        [5 6 7] [4 3 2 1]
-

Definition

+

Definition

[drop] [take] clop

-

Discussion

+

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.

- +

split_list

split_list

@@ -2072,13 +1928,13 @@ a F a 
   [1 2 3 4 5 6 7] 4 split_list
 ----------------------------------
         [1 2 3 4] [5 6 7]
-

Definition

+

Definition

[take reverse] [drop] clop

-

Discussion

+

Discussion

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

- +

split_at

sqr

@@ -2087,7 +1943,7 @@ a F a 
   n  sqr
 ------------
      n²
-

Definition

+

Definition

dup mul

@@ -2095,9 +1951,21 @@ a F a

sqrt

Basis Function Combinator

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

-

Discussion

+

Discussion

Another “numeric tower” hatch…

+

stackd

+

Function

+

Grab the stack under the top item and put it onto the stack.

+

Example

+
   ... 1 2 3 stackd
+------------------------
+  ... 1 2 [2 1 ...] 3
+

Definition

+
+

[stack] dip

+
+

stack

Function

Put the stack onto the stack.

@@ -2108,23 +1976,11 @@ a F a

[] swaack dup swaack first

-

Discussion

+

Discussion

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

- +

[unstack] enstacken disenstacken

-

stackd

-

Function

-

Grab the stack under the top item and put it onto the stack.

-

Example

-
   ... 1 2 3 stackd
-------------------------
-  ... 1 2 [2 1 ...] 3
-

Definition

-
-

[stack] dip

-
-

step

Combinator

Run a quoted program on each item in a sequence.

@@ -2141,9 +1997,9 @@ a F a ... [a b c] [Q] . step ---------------------------------------- ... a . Q [b c] [Q] step -

Discussion

+

Discussion

See the Recursion Combinators notebook.

- +

step_zero

step_zero

@@ -2152,13 +2008,13 @@ a F a 
   [...] [F] step_zero
 -------------------------
      0 [...] [F] step
-

Definition

+

Definition

0 roll> step

-

Discussion

+

Discussion

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

- +

step

stuncons

@@ -2168,7 +2024,7 @@ a F a 
   1 2 3 stuncons
 --------------------
    1 2 3 3 [2 1]
-

Definition

+

Definition

stack uncons

@@ -2180,11 +2036,11 @@ a F a 
   1 2 3 stununcons
 ----------------------
     1 2 3 3 2 [1]
-

Definition

+

Definition

stack uncons uncons

- +

stuncons

sub

@@ -2193,17 +2049,17 @@ a F a 
   a b sub
 -------------
     (a-b)
- +

add

succ

Function

Successor. Increment TOS.

-

Definition

+

Definition

1 +

- +

pred

sum

@@ -2213,11 +2069,11 @@ a F a 
   [1 2 3 4 5] sum
 ---------------------
          15
-

Definition

+

Definition

[+] step_zero

- +

size

swaack

@@ -2227,41 +2083,41 @@ a F a 
   1 2 3 [4 5 6] swaack
 --------------------------
    6 5 4 [3 2 1]
-

Discussion

+

Discussion

This function works as a kind of “context switch”. It’s used in the definition of infra.

- +

infra

-

swap

-

Basis Function

-

Swap the top two items on the stack.

-
   a b swap
---------------
-     b a
- -

swapd

-

swapd

Function

Swap the second and third items on the stack.

   a b c swapd
 -----------------
       b a c
-

Definition

+

Definition

[swap] dip

- +

over tuck

+

swap

+

Basis Function

+

Swap the top two items on the stack.

+
   a b swap
+--------------
+     b a
+ +

swapd

+

swoncat

Function

concat two lists, but swap the lists first.

-

Definition

+

Definition

swap concat

- +

concat

swons

@@ -2270,7 +2126,7 @@ a F a 
   [...] a swons
 -------------------
       [a ...]
-

Definition

+

Definition

swap cons

@@ -2278,14 +2134,14 @@ a F a

tailrec

Combinator

A specialization of the genrec combinator.

-

Definition

+

Definition

[i] genrec

-

Discussion

+

Discussion

Some recursive functions do not need to store additional data or pending actions per-call. These are called “tail recursive” functions. In Joy, they appear as genrec definitions that have i for the second half of their recursive branch.

See the Recursion Combinators notebook.

- +

genrec

take

@@ -2294,9 +2150,9 @@ a F a 
   [a b c d] 2 take
 ----------------------
         [b a]
-

Definition

+

Definition

-

<<{} [shift] times pop

+

<<{} [shift] times pop

ternary

@@ -2305,13 +2161,13 @@ a F a 
   ... z y x [P] ternary
 -------------------------
          ... a
-

Definition

+

Definition

binary popd

-

Discussion

+

Discussion

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

- +

binary nullary unary

third

@@ -2319,11 +2175,11 @@ a F a 
   [a b c ...] third
 -----------------------
            c
-

Definition

+

Definition

rest second

- +

first second fourth rest

times

@@ -2340,11 +2196,11 @@ a F a ... n [Q] . times ------------------------------------- w/ n > 1 ... . Q (n-1) [Q] times -

Definition

+

Definition

[-- dip] cons [swap] infra [0 >] swap while pop :

-

Discussion

+

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                                                                                                                          
@@ -2367,11 +2223,11 @@ a F a
   a b tuck
 --------------
     b a b
-

Definition

+

Definition

dup [swap] dip

- +

over

unary

@@ -2380,13 +2236,13 @@ a F a 
   ... x [P] unary
 ---------------------
        ... a
-

Definition

+

Definition

nullary popd

-

Discussion

+

Discussion

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

- +

binary nullary ternary

uncons

@@ -2395,9 +2251,9 @@ a F a 
   [a ...] uncons
 --------------------
       a [...]
-

Discussion

+

Discussion

This is the inverse of cons.

- +

cons

unique

@@ -2409,7 +2265,7 @@ a F a 
   a unit
 ------------
     [a]
-

Definition

+

Definition

[] cons

@@ -2421,11 +2277,11 @@ a F a 
   1 2 [3 4] 5 unquoted
 --------------------------
          1 2 3 4 5
-

Definition

+

Definition

[i] dip

- +

unit

unswons

@@ -2433,11 +2289,31 @@ a F a 
   [a ...] unswons
 ---------------------
        [...] a
-

Definition

+

Definition

uncons swap

+

||

+

Combinator

+

Short-circuiting Boolean OR

+

Definition

+
+

nulco [nullary] dip [true] branch

+
+

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

&&

+

void

Basis Function

True if the form on TOS is void otherwise False.

diff --git a/docs/html/css/func_ref.css b/docs/html/css/func_ref.css new file mode 100644 index 0000000..793ed51 --- /dev/null +++ b/docs/html/css/func_ref.css @@ -0,0 +1,33 @@ + +body { + background: #fff; + color: black; + font-family: 'EB Garamond 12'; +} + +footer { + margin-top: 2em; + font-family: 'EB Garamond SC 08'; + font-size: x-small; + text-align: center; +} + +code { + background: #eee; +} + +pre { + background: #eee; + margin-left: 2em; + margin-right: 2em; + margin-bottom: 1em; + font-family: 'Inconsolata'; + padding: 0.5em; +} + +blockquote { + font-family: monospace, 'Inconsolata'; + background: #eee; + border-left: 0.2em solid black; + padding: 0.5em; +} diff --git a/docs/reference/FuncRef.html b/docs/reference/FuncRef.html index 09ce269..4918cc4 100644 --- a/docs/reference/FuncRef.html +++ b/docs/reference/FuncRef.html @@ -13,6 +13,8 @@ div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} ul.task-list{list-style: none;} + +
@@ -211,6 +213,7 @@
  • zip
    • +

    Home

    Version -10.0.0

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

    diff --git a/docs/reference/Function-Reference.md b/docs/reference/Function-Reference.md index 92f526e..71c34da 100644 --- a/docs/reference/Function-Reference.md +++ b/docs/reference/Function-Reference.md @@ -1,4 +1,5 @@ -# Thun Function Reference + +[Home](/) Version -10.0.0 diff --git a/docs/reference/HEADER.md b/docs/reference/HEADER.md deleted file mode 100644 index 272101b..0000000 --- a/docs/reference/HEADER.md +++ /dev/null @@ -1,5 +0,0 @@ - -Version -10.0.0 - -Each function, combinator, or definition should be documented here. - diff --git a/docs/reference/Makefile b/docs/reference/Makefile index b869f56..9e6e355 100644 --- a/docs/reference/Makefile +++ b/docs/reference/Makefile @@ -1,17 +1,11 @@ -FUNCDOCS = $(wildcard ../*.md) TITLE = --metadata title="Thun Function Reference" TOC = --toc --toc-depth=2 +CSS = --css=/css/fonts.css --css=/css/func_ref.css all: mov FuncRef.html: Function-Reference.md - pandoc -s $(TOC) $(TITLE) --ascii Function-Reference.md -o FuncRef.html - -Function-Reference.md: HEADER.md $(FUNCDOCS) - awk 'FNR==1 && NR > 1 {print ""}1' HEADER.md $(FUNCDOCS) > Function-Reference.md - -# https://stackoverflow.com/questions/8183191/concatenating-files-and-insert-new-line-in-between-files -# WTF would we do w/o the Internet? Know our tools well? + pandoc -s $(TOC) $(TITLE) $(CSS) --ascii Function-Reference.md -o FuncRef.html mov: FuncRef.html - cp -v $? ../../html/ + cp -v $? ../html/ -- 2.11.0