From 466bf3d79bd1b71ef9308315c9ffa573e2d5c093 Mon Sep 17 00:00:00 2001 From: Simon Forman Date: Fri, 16 Sep 2022 12:28:13 -0700 Subject: [PATCH] A bit more docs. --- README.md | 143 +++++++++++++++++++------------------------ docs/html/index.html | 114 +++++++++++++++------------------- 2 files changed, 112 insertions(+), 145 deletions(-) diff --git a/README.md b/README.md index fe05f50..f6149a8 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ A Dialect of Joy. -version 0.5.0 +Version 0.5.0 > Simple pleasures are the best. @@ -27,6 +27,13 @@ and a great deal of fascinating material mostly written by Von Thun on Joy and its deeper facets as well as how to program in it and several interesting aspects. It's quite a treasure trove. +[Wikipedia entry for Joy](https://en.wikipedia.org/wiki/Joy_%28programming_language%29) + +[Homepage at La Trobe University](http://www.latrobe.edu.au/humanities/research/research-projects/past-projects/joy-programming-language) + +[The original Thun/Joypy site](https://web.archive.org/web/20220411010035/https://joypy.osdn.io/) + + ## Example Code Here is an example of Joy code: @@ -90,113 +97,89 @@ coordinate pair in a square spiral (like the kind used to construct an ## Documentation -### Jupyter Notebooks +### [Jupyter Notebooks](/notebooks/index.html) -[Notebooks](/notebooks/index.html) - -The docs/notebooks dir contains Jupyter notebooks, ... TODO - -### Function Reference - -[Function Reference](/FuncRef.html) +### [Function Reference](/FuncRef.html) ### Building the Docs -Run `make` in the `docs` directory. +Run `make` in the `docs` directory. (This is a lie, it's more complex than +that. Really you need to run (GNU) make in the `docs/notebooks` and +`docs/reference` dirs first, _then_ run `make` in the `docs` directory.) + + +## Installation + +Clone the repo and follow the instructions in the individual `implementations` directories. ## Basics of Joy -Joy is stack-based. There is a main stack that holds data items: -integers, bools, symbols, and sequences or quotes which hold -data items themselves. +Joy is built around three things: a __stack__ of data items, an __expression__ +representing a program to evaluate, and a __dictionary__ of named functions. - 23 dup [21 18 /] [1 [2 [3]]] +Joy is [stack-based](https://en.wikipedia.org/wiki/Stack-oriented_programming_language). +There is a single main __stack__ that holds data items, which can be integers, bools, +symbols (names), or sequences of data items enclosed in square brackets (`[` or `]`). -A Joy expression is just a sequence (a.k.a. "list") of items. Sequences + 23 dup [21 18 add] true false [1 [2 [3]]] cons + +A Joy __expression__ is just a sequence or list of items. Sequences intended as programs are called "quoted programs". Evaluation proceeds -by iterating through the terms in the expression, putting all literals -onto the main stack and executing functions as they are encountered. -Functions receive the current stack and return the next stack. +by iterating through the terms in an expression putting all literals (integers, bools, or lists) +onto the main stack and executing functions named by symbols as they are encountered. +Functions receive the current stack, expression, and dictionary and return the next stack. + +The __dictionary__ associates symbols (strings) with Joy expressions that define the +available functions of the Joy system. Together the stack, expression, and dictionary +are the entire state of the Joy interpreter. + + +### Stack / Quote / List / Sequence + +When talking about Joy we use the terms "stack", "quote", "sequence", +"list", and others to mean the same thing: a simple linear datatype that +permits certain operations such as iterating and pushing and popping +values from (at least) one end. + +> In describing Joy I have used the term quotation to describe all of the +> above, because I needed a word to describe the arguments to combinators +> which fulfill the same role in Joy as lambda abstractions (with +> variables) fulfill in the more familiar functional languages. I use the +> term list for those quotations whose members are what I call literals: +> numbers, characters, truth values, sets, strings and other quotations. +> All these I call literals because their occurrence in code results in +> them being pushed onto the stack. But I also call [London Paris] a list. +> So, [dup *] is a quotation but not a list. + +From ["A Conversation with Manfred von Thun" w/ Stevan Apter](http://archive.vector.org.uk/art10000350 + + ### Literals and Simple Functions - joy? 1 2 3 - . 1 2 3 - 1 . 2 3 - 1 2 . 3 - 1 2 3 . - - 1 2 3 <-top - - joy? + + - 1 2 3 . + + - 1 5 . + - 6 . - - 6 <-top - - joy? 7 * - 6 . 7 * - 6 7 . * - 42 . - - 42 <-top - - joy? +TODO ### Combinators The main loop is very simple as most of the action happens through what -are called "combinators": functions which accept quoted programs on the -stack and run them in various ways. These combinators factor specific -patterns that provide the effect of control-flow in other languages (such -as ifte which is like if..then..else..) Combinators receive the current +are called __combinators__. These are functions which accept quoted programs on the +stack and run them in various ways. These combinators reify specific +control-flow patterns (such as `ifte` which is like `if.. then.. else..` in other +languages.) Combinators receive the current expession in addition to the stack and return the next expression. They work by changing the pending expression the interpreter is about to -execute. The combinators could work by making recursive calls to the +execute. (The combinators could work by making recursive calls to the interpreter and all intermediate state would be held in the call stack of the implementation language, in this joy implementation they work instead -by changing the pending expression and intermediate state is put there. +by changing the pending expression and intermediate state is put there.) joy? 23 [0 >] [dup --] while - - ... - - -> 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 + 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 -## TODO: - -§.4.4 Definitions and More Elaborate Functions - -§.4.5 Programming and Metaprogramming - -§.4.6 Refactoring - - -§.6 References & Further Reading - - -[Wikipedia entry for Joy](https://en.wikipedia.org/wiki/Joy_%28programming_language%29) - -[Homepage at La Trobe University](http://www.latrobe.edu.au/humanities/research/research-projects/past-projects/joy-programming-language) - -[The original Thun/Joypy site](https://web.archive.org/web/20220411010035/https://joypy.osdn.io/) - - --------------------------------------------------- - -Misc... - -Stack based - literals (as functions) - functions - combinators - -Refactoring and making new definitions - traces and comparing -performance - metaprogramming as programming, even the lowly integer -range function can be expressed in two phases: building a specialized -program and then executing it with a combinator - ?Partial evaluation? -- ?memoized dynamic dependency graphs? - algebra -------------------------------------------------- diff --git a/docs/html/index.html b/docs/html/index.html index 370b293..3d9741e 100644 --- a/docs/html/index.html +++ b/docs/html/index.html @@ -8,7 +8,7 @@

Thun

A Dialect of Joy.

-

version 0.5.0

+

Version 0.5.0

Simple pleasures are the best.

@@ -31,6 +31,9 @@ which contains source code for the original C interpreter, Joy language source c and a great deal of fascinating material mostly written by Von Thun on Joy and its deeper facets as well as how to program in it and several interesting aspects. It's quite a treasure trove.

+

Wikipedia entry for Joy

+

Homepage at La Trobe University

+

The original Thun/Joypy site

Example Code

Here is an example of Joy code:

square_spiral ≡ [_p] [_then] [_else] ifte
@@ -85,83 +88,64 @@ coordinate pair in a square spiral (like the kind used to construct an
      `-- defs.txt - common Joy definitions for all interpreters

Documentation

-

Jupyter Notebooks

-

Notebooks

-

The docs/notebooks dir contains Jupyter notebooks, ... TODO

-

Function Reference

-

Function Reference

+

Jupyter Notebooks

+

Function Reference

Building the Docs

-

Run make in the docs directory.

+

Run make in the docs directory. (This is a lie, it's more complex than +that. Really you need to run (GNU) make in the docs/notebooks and +docs/reference dirs first, then run make in the docs directory.)

+

Installation

+

Clone the repo and follow the instructions in the individual implementations directories.

Basics of Joy

-

Joy is stack-based. There is a main stack that holds data items: -integers, bools, symbols, and sequences or quotes which hold -data items themselves.

-
23 dup [21 18 /] [1 [2 [3]]]
+
Joy is built around three things: a stack of data items, an expression
+representing a program to evaluate, and a dictionary of named functions.

+
Joy is stack-based.
+There is a single main stack that holds data items, which can be integers, bools,
+symbols (names), or sequences of data items enclosed in square brackets ([ or ]).

+
23 dup [21 18 add] true false [1 [2 [3]]] cons
 

-
A Joy expression is just a sequence (a.k.a. "list") of items.  Sequences
+
A Joy expression is just a sequence or list of items.  Sequences
 intended as programs are called "quoted programs".  Evaluation proceeds
-by iterating through the terms in the expression, putting all literals
-onto the main stack and executing functions as they are encountered.
-Functions receive the current stack and return the next stack.

+by iterating through the terms in an expression putting all literals (integers, bools, or lists)
+onto the main stack and executing functions named by symbols as they are encountered.
+Functions receive the current stack, expression, and dictionary and return the next stack.

+
The dictionary associates symbols (strings) with Joy expressions that define the
+available functions of the Joy system.  Together the stack, expression, and dictionary
+are the entire state of the Joy interpreter.

+
Stack / Quote / List / Sequence

+
When talking about Joy we use the terms "stack", "quote", "sequence",
+"list", and others to mean the same thing: a simple linear datatype that
+permits certain operations such as iterating and pushing and popping
+values from (at least) one end.

+

+
In describing Joy I have used the term quotation to describe all of the
+above, because I needed a word to describe the arguments to combinators
+which fulfill the same role in Joy as lambda abstractions (with
+variables) fulfill in the more familiar functional languages. I use the
+term list for those quotations whose members are what I call literals:
+numbers, characters, truth values, sets, strings and other quotations.
+All these I call literals because their occurrence in code results in
+them being pushed onto the stack. But I also call [London Paris] a list.
+So, [dup *] is a quotation but not a list.

+

+
From ["A Conversation with Manfred von Thun" w/ Stevan Apter](http://archive.vector.org.uk/art10000350

 
Literals and Simple Functions

-
joy? 1 2 3
-      . 1 2 3
-    1 . 2 3
-  1 2 . 3
-1 2 3 .
-
-1 2 3 <-top
-
-joy? + +
-1 2 3 . + +
-  1 5 . +
-    6 .
-
-6 <-top
-
-joy? 7 *
-  6 . 7 *
-6 7 . *
- 42 .
-
-42 <-top
-
-joy?
-

+
TODO

 
Combinators

 
The main loop is very simple as most of the action happens through what
-are called "combinators": functions which accept quoted programs on the
-stack and run them in various ways.  These combinators factor specific
-patterns that provide the effect of control-flow in other languages (such
-as ifte which is like if..then..else..)  Combinators receive the current
+are called combinators. These are functions which accept quoted programs on the
+stack and run them in various ways.  These combinators reify specific
+control-flow patterns (such as ifte which is like if.. then.. else.. in other
+languages.)  Combinators receive the current
 expession in addition to the stack and return the next expression.  They
 work by changing the pending expression the interpreter is about to
-execute.  The combinators could work by making recursive calls to the
+execute.  (The combinators could work by making recursive calls to the
 interpreter and all intermediate state would be held in the call stack of
 the implementation language, in this joy implementation they work instead
-by changing the pending expression and intermediate state is put there.

+by changing the pending expression and intermediate state is put there.)

 
joy? 23 [0 >] [dup --] while
-
-...
-
--> 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
+23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
 

-
TODO:

-
§.4.4 Definitions and More Elaborate Functions

-
§.4.5 Programming and Metaprogramming

-
§.4.6 Refactoring

-
§.6 References & Further Reading

-
Wikipedia entry for Joy

-
Homepage at La Trobe University

-
The original Thun/Joypy site

-

-
Misc...

-
Stack based - literals (as functions) - functions - combinators -
-Refactoring and making new definitions - traces and comparing
-performance - metaprogramming as programming, even the lowly integer
-range function can be expressed in two phases: building a specialized
-program and then executing it with a combinator - ?Partial evaluation?
-- ?memoized dynamic dependency graphs? - algebra

 

 
Copyright © 2014-2022 Simon Forman

 
This file is part of Thun