Thun Function Reference

Not negative.

    n !-
----------- n < 0
   false


   n !-
---------- n >= 0
   true

See ne.

See mod.

See and.

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

   [A] [B] &&
---------------- true
        B


   [A] [B] &&
---------------- false
     false

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.

See mul.

See add.

See succ.

See sub.

See pred.

See floordiv.

See floordiv.

See floordiv.

See lt.

See lshift.

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

See le.

See ne.

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

See eq.

See gt.

See ge.

See rshift.

Is the item on the top of the stack "truthy"?

See xor.

Return the absolute value of the argument.

Add two numbers together: a + b.

Build a list of values from a generator program G and a stopping predicate P.

           [P] [G] anamorphism
-----------------------------------------
   [P] [pop []] [G] [dip swons] genrec

Example

The range function generates a list of the integers from 0 to n - 1:

[0 <=] [-- dup] anamorphism

Logical bit-wise AND.

"apply one"

Given a quoted program on TOS and anything as the second stack item run the program without disturbing the stack and replace the two args with the first result of the program.

         ... x [Q] app1
---------------------------------
   ... [x ...] [Q] infra first

This is the same effect as the unary combinator.

Like app1 with two items.

   ... y x [Q] . app2
-----------------------------------
   ... [y ...] [Q] . infra first
       [x ...] [Q]   infra first

Like [app1] with three items.

     ... z y x [Q] . app3
-----------------------------------
   ... [z ...] [Q] . infra first
       [y ...] [Q]   infra first
       [x ...] [Q]   infra first

Like [app1] with any number of items.

   ... xN ... x2 x1 x0 [Q] n . appN
--------------------------------------
   ... [xN ...] [Q] . infra first
                   ...
       [x2 ...] [Q]   infra first
       [x1 ...] [Q]   infra first
       [x0 ...] [Q]   infra first

See getitem.

Compute the average of a list of numbers. (Currently broken until I can figure out what to do about "numeric tower" in Thun.)

Run two quoted programs

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

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

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

Use a Boolean value to select and run one of two quoted programs.

   false [F] [T] branch
--------------------------
          F

   true [F] [T] branch
-------------------------
             T

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

Do [cons] four times.

   a b [...] ccons
---------------------
      [a b ...]

Do [cons] two times.

Use a Boolean value to select one of two items.

   a b false choice
----------------------
          a

   a b true choice
---------------------
          b

Clear everything from the stack.

Run two programs in parallel, consuming one additional item, and put their results on the stack.

   ... x [A] [B] cleave
------------------------
        ... a b

Derivation

[fork] [popdd]

Example

   1 2 3 [+] [-] cleave
--------------------------
         1 2 5 -1

Run two programs in parallel, consuming two additional items, and put their results on the stack.

   ... x y [A] [B] clop
--------------------------
        ... a b

Take two values and three quoted programs on the stack and run one of the three depending on the results of comparing the two values.

   a b [G] [E] [L] cmp
------------------------- a > b
        G

   a b [G] [E] [L] cmp
------------------------- a = b
            E

   a b [G] [E] [L] cmp
------------------------- a < b
                L

Take a quoted program from the stack, [cons] the next item onto it, then [dip] the whole thing under what was the third item on the stack.

   a b [F] . codi
--------------------
         b . F a

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

Concatinate two lists.

   [a b c] [d e f] concat
----------------------------
       [a b c d e f]

This combinator works like a case statement. It expects a single quote on the stack that must contain zero or more condition quotes and a default quote. Each condition quote should contain a quoted predicate followed by the function expression to run if that predicate returns true. If no predicates return true the default function runs.

[
    [ [Predicate0] Function0 ]
    [ [Predicate1] Function1 ]
    ...
    [ [PredicateN] FunctionN ]
    [Default]
]
cond

Given an item and a list, append the item to the list to make a new list.

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

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

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

Like [dip] but expects two items.

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

Like [dip] but expects three items. :

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

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

See floordiv.

    x y divmod
------------------
     q      r
   (x/y)  (x%y)

Invariant: qy + r = x.

Given a number greater than zero put all the Natural numbers (including zero) less than that onto the stack.

Example

   3 down_to_zero
--------------------
      3 2 1 0

Expects an integer and a quote on the stack and returns the quote with n items removed off the top.

Example

   [a b c d] 2 drop
----------------------
       [c d]

"Dup"licate the top item on the stack.

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

[dup] the second item down on the stack.

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

[dup] the third item down on the stack.

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

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

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

Derivation

a [F] dupdip
a [F] dupd dip
a [F] [dup] dip dip
a dup [F] dip
a a [F] dip
a F a

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

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

Put the stack onto the stack replacing the contents of the stack.

   ... a b c enstacken
-------------------------
       [c b a ...]

Compare the two items on the top of the stack for equality and replace them with a Boolean value.

   a b eq
-------------
   Boolean
   (a = b)

Replace a list with its first item.

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

Replace a list with its first two items.

   [a b ...] first_two
-------------------------
           a b

Given a list of lists, concatinate them.

Example

   [[1 2] [3 [4] 5] [6 7]] flatten
-------------------------------------
          [1 2 3 [4] 5 6 7]

Return the largest integer \<= x.

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)

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

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

Replace a list with its fourth item.

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

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

Compiled GCD function.

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

   a b ge
--------------
   Boolean
   (a >= b)

General Recursion Combinator.

                      [if] [then] [rec1] [rec2] genrec
---------------------------------------------------------------------
   [if] [then] [rec1 [[if] [then] [rec1] [rec2] genrec] rec2] ifte

Expects an integer and a quote on the stack and returns the item at the nth position in the quote counting from 0.

Example

   [a b c d] 2 getitem
-------------------------
        c

Expect a number on the top of the stack and [cons] that many items from under it onto a new list.

Example

   a b c d e 3 grabN
-----------------------
      a b [c d e]

A weird function used in [app2] that does this:

      ... 1 2 3 4 5 grba
-------------------------------
   ... 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.

Greater-than comparison of two numbers.

   a b gt
--------------
   Boolean
   (a > b)

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

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

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

Append a quoted expression onto the pending expression.

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

The identity function.

If-Then-Else combinator, a common and convenient specialization of [branch].

        [if] [then] [else] ifte
---------------------------------------
   [if] nullary [else] [then] branch

Take a quoted program from the stack and run it twice, first under the top item, then again with the top item.

... a [Q] ii
------------------
 ... Q a Q

Example

It's a little tricky to understand how this works so here's an example trace:

      1 2 3 4 [++] • [dip] dupdip i
1 2 3 4 [++] [dip] • dupdip i
      1 2 3 4 [++] • dip [++] i
             1 2 3 • ++ 4 [++] i
             1 2 4 • 4 [++] i
           1 2 4 4 • [++] i
      1 2 4 4 [++] • i
           1 2 4 4 • ++
           1 2 4 5 •

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


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

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

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

Less-Than-or-Equal-to comparison of the two items on the top of the stack, replacing them with a Boolean value.

   a b le
-------------
   Boolean
   (a <= b)

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.

   false [Q] loop
--------------------


   true [Q] . loop
--------------------------
            . Q [Q] loop

Logical Left-Shift

   a n lshift
----------------
     (a×2ⁿ)

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

   a b lt
-------------
   Boolean
   (a < b)

Given an initial state value and a quoted generator function build a generator quote.

   state [generator function] make_generator
-----------------------------------------------
     [state [generator function] codireco]

Example

   230 [dup ++] make_generator
---------------------------------
     [230 [dup ++] codireco]

And then:

   [230 [dup ++] codireco] 5 [x] times pop
---------------------------------------------
             230 231 232 233 234

Given a list of items and a quoted program run the program for each item in the list (with the rest of the stack) and replace the old list and the program with a list of the results.

Example

   5 [1 2 3] [++ *] map
--------------------------
       5 [10 15 20]

Given a list find the maximum.

Example

   [1 2 3 4] max
-------------------
         4

Given a list find the minimum.

Example

   [1 2 3 4] min
-------------------
         1

Return the remainder of a divided by b.

   a b mod
-------------
    (a%b)

See mod.

Multiply two numbers.

   a b mul
-------------
    (a×b)

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)

Invert the sign of a number.

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

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

   true not
--------------
    false

   false not
---------------
     true

Take the item on the top of the stack and [cons] it onto [nullary].

     [F] nulco
-------------------
   [[F] nullary]

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

   ... [P] nullary
---------------------
        ... a

Example

... [P] nullary
... [P] [stack] dip infra first
... stack [P] infra first
... [...] [P] infra first
... [a ...] first
...  a

Like [getitem] but [swap]s the order of arguments.

Example

   2 [a b c d] of
--------------------
         c

Logical bit-wise OR.

[dup] the second item on the stack over the first.

   a b over
--------------
    a b a

Definition

There are many many ways to define this function.

[swap] [tuck]

[[pop]] [nullary]

[[dup]] [dip] [swap]

[unit] [dupdip]

[unit] [dupdipd] [first]

And so on...

Take a list of quoted functions from the stack and replace it with a list of the [first] results from running those functions (on copies of the rest of the stack.)

Example

   5 7 [[+][-][*][/][%]] pam
-------------------------------
      5 7 [12 -2 35 0 5]

See getitem.

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

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

Pop the top item from the stack and discard it.

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

[pop] the second item down on the stack.

   a b popd
--------------
      b

[pop] the third item on the stack.

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

[pop] two items from the stack.

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

[pop] the second and third items from the stack.

   a b c popopd
------------------
        c

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

[pop] three items from the stack.

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

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

Example

   2 [2 3 4 5 6 7 8 9] [pow] map
-----------------------------------
    2 [4 8 16 32 64 128 256 512]

Predecessor. Decrement TOS.

From the "Overview of the language JOY"

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

5 [1] [*] primrec

Then primrec tests whether the top element on the stack (initially the 5) is equal to zero. If it is, it pops it off and executes one of the quotations, the [1] which leaves 1 on the stack as the result. Otherwise it pushes a decremented copy of the top element and recurses. On the way back from the recursion it uses the other quotation, [*], to multiply what is now a factorial on top of the stack by the second element on the stack.

   0 [Base] [Recur] primrec
------------------------------
      Base

         n [Base] [Recur] primrec
------------------------------------------ n > 0
   n (n-1) [Base] [Recur] primrec Recur

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

Definition

1 [swap] [[mul]] [step]

Or,

[1] [[mul]] [primrec]

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

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

Expect a number n on the stack and replace it with a list: [(n-1)...0].

Example

     5 range
-----------------
   [4 3 2 1 0]

   -5 range
--------------
      []

Take a number n from the stack and replace it with a list [0...n].

Example

   5 range_to_zero
---------------------
    [0 1 2 3 4 5]

Replace the first item in a list with the item under it.

   a [b ...] reco
--------------------
     [a ...]

See mod.

See mod.

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.

   [1 2 3 1] 1 remove
------------------------
        [2 3 1]

Definition

See the "Remove Function" notebook.

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

Reverse the list on the top of the stack.

Example

   [1 2 3] reverse
---------------------
       [3 2 1]

See rolldown.

See rollup.

   a b c rolldown
--------------------
       b c a

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

Round a number to a given precision in decimal digits.

   [a b ...] rrest
---------------------
        [...]

Logical Right-Shift

   a n rshift
----------------
     (a∕2ⁿ)

Run a quoted program in a list.

Example

   [1 2 +] run
-----------------
       [3]

   [a b ...] second
----------------------
          b

Use a Boolean value to select one of two items from a sequence. :

   [a b] false select
------------------------
           a

   [a b] true select
-----------------------
           b

Print redistribution information.

Move the top item from one list to another.

Example

   [x y z] [a b c] shift
---------------------------
      [a x y z] [b c]

Like [concat] but [reverse] the top list into the second.

Example

   [a b c] [d e f] shunt
---------------------------
       [f e d a b c]

Replace a list with its size.

Example

   [23 [cats] 4] size
------------------------
           3

Given a list return it sorted.

Example

   [4 2 5 7 1] sort
----------------------
      [1 2 4 5 7]

Example code.

Split a list (second on the stack) at the position given by the number on the top of the stack.

Example

   [1 2 3 4 5 6 7] 4 split_at
--------------------------------
       [5 6 7] [4 3 2 1]

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.

   [1 2 3 4 5 6 7] 4 split_list
----------------------------------
        [1 2 3 4] [5 6 7]

Square the number on the top of the stack.

   n  sqr
------------
     n²

Function Combinator

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

Put the stack onto the stack.

      ... c b a stack
---------------------------
   ... c b a [a b c ...]

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

Example

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

Run a quoted program on each item in a sequence.

   ... [] [Q] step
---------------------
         ...


   ... [a] [Q] step
----------------------
      ... a Q


   ... [a b c] [Q] . step
----------------------------------------
             ... a . Q [b c] [Q] step

Like [step] but with 0 as the initial value.

   [...] [F] step_zero
-------------------------
     0 [...] [F] step

Take the [stack] and [uncons] the top item.

Example

   1 2 3 stuncons
--------------------
   1 2 3 3 [2 1]

Take the [stack] and [uncons] the top two items.

Example

   1 2 3 stununcons
----------------------
    1 2 3 3 2 [1]

Subtract the number on the top of the stack from the number below it.

   a b sub
-------------
    (a-b)

Successor. Increment TOS.

Given a quoted sequence of numbers return the sum.

Example

   [1 2 3 4 5] sum
---------------------
         15

Swap stack. Take a list from the top of the stack, replace the stack with the list, and put the old stack onto it.

Example

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

Swap the top two items on the stack.

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

Swap the second and third items on the stack.

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

[concat] two lists, but [swap] the lists first.

Like [cons] but [swap] the item and list.

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

A specialization of the [genrec] combinator.

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.

   [a b c d] 2 take
----------------------
        [b a]

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

   ... z y x [P] ternary
-------------------------
         ... a

   [a b c ...] third
-----------------------
           c

Expect a quoted program and an integer n on the stack and do the program n times.

   ... n [Q] . times
-----------------------  w/ n <= 0
         ... .

   ... 1 [Q] . times
-----------------------
         ... . Q

   ... n [Q] . times
-------------------------------------  w/ n > 1
         ... . Q (n-1) [Q] times

See bool.

[dup] the item on the top of the stack under the second item on the stack.

   a b tuck
--------------
    b a b

(Combinator)

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

   ... x [P] unary
---------------------
       ... a

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.

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

Given a list remove duplicate items.

   a unit
------------
    [a]

Unquote (using [i]) the list that is second on the stack.

Example

   1 2 [3 4] 5 unquoted
--------------------------
         1 2 3 4 5

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

True if the form on TOS is void otherwise False.

Print warranty information.

A specialization of [loop] that accepts a quoted predicate program P and runs it [nullary].

   [P] [F] while
------------------- P -> false

    [P] [F] while
--------------------- P -> true
   F [P] [F] while

Print all the words in alphabetical order.

Take a quoted function F and run it with itself as the first item on the stack.

   [F] x
-----------
   [F] F

Logical bit-wise eXclusive OR.

Replace the two lists on the top of the stack with a list of the pairs from each list. The smallest list sets the length of the result list.

Example

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

Short-circuiting Boolean OR