README

   1
   2
   3                 Thun
   4
   5   Dialects of Joy in Python.
   6
   7                v0.4.2
   8
   9
  10 --------------------------------------------------
  11
  12
  13 Copyright © 2014-2020 Simon Forman
  14
  15 This file is part of Thun
  16
  17 Thun is free software: you can redistribute it and/or modify it under the
  18 terms of the GNU General Public License as published by the Free Software
  19 Foundation, either version 3 of the License, or (at your option) any
  20 later version.
  21
  22 Thun is distributed in the hope that it will be useful, but WITHOUT ANY
  23 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  24 FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
  25 details.
  26
  27 You should have received a copy of the GNU General Public License along
  28 with Thun.  If not see <http://www.gnu.org/licenses/>.
  29
  30
  31 --------------------------------------------------
  32
  33
  34 §.1 Introduction
  35
  36 Joy is a programming language created by Manfred von Thun that is easy to
  37 use and understand and has many other nice properties.  This project
  38 implements Python and Prolog interpreters for dialects that attempts to
  39 stay very close to the spirit of Joy but does not precisely match the
  40 behaviour of the original version written in C.
  41
  42 The best source (no pun intended) for learning about Joy is the
  43 information made available at the website of La Trobe University (see the
  44 references section below for the URL) which contains source code for the
  45 original C interpreter, Joy language source code for various functions,
  46 and a great deal of fascinating material mostly written by Von Thun on
  47 Joy and its deeper facets as well as how to program in it and several
  48 interesting aspects.  It's quite a treasure trove.
  49
  50
  51 §.2 Installation
  52
  53 From PyPI in the usual way, e.g.:
  54
  55     pip install Thun
  56
  57 Or if you have downloaded the source, from the top directory:
  58
  59     python ./setup.py install
  60
  61 Or you can run the package directly from the top directory.
  62
  63 To start a crude REPL:
  64
  65     python -m joy
  66
  67 There is a "quiet" mode for e.g. using joy from a shell script:
  68
  69     python -m joy -q
  70
  71 This supresses the initial banner output and the prompt text.
  72
  73
  74 §.3 Documentation
  75
  76 §.3.1 Jupyter Notebooks
  77
  78 The docs/ folder contains Jupyter notebooks, ... TODO
  79
  80 §.3.2 Sphinx Docs
  81
  82 Some of the documentation is in the form of ReST files
  83
  84 §.3.3 Building the Docs
  85
  86 Building the documentation is a little tricky at the moment.  It involves
  87 a makefile that uses nbconvert to generate ReST files from some of the
  88 notebooks, copies those to the sphinx source dir, then builds the HTML
  89 output using sphinx.
  90
  91 Get the dependencies for (re)building the docs:
  92
  93     pip install Thun[build-docs]
  94     make docs
  95
  96
  97 §.4 Basics of Joy
  98
  99 Joy is stack-based.  There is a main stack that holds data items:
 100 integers, floats, strings, functions, and sequences or quotes which hold
 101 data items themselves.
 102
 103     23 1.8 'a string' "another" dup [21 18 /] [1 [2 [3]]]
 104
 105 A Joy expression is just a sequence (a.k.a. "list") of items.  Sequences
 106 intended as programs are called "quoted programs".  Evaluation proceeds
 107 by iterating through the terms in the expression, putting all literals
 108 onto the main stack and executing functions as they are encountered.
 109 Functions receive the current stack and return the next stack.
 110
 111 §.4.1 Python Semantics
 112
 113 In general, where otherwise unspecified, the semantics of Thun are that
 114 of the underlying Python. That means, for example, that integers are
 115 unbounded (whatever your machine can handle), strings cannot be added to
 116 integers but can be multiplied, Boolean True and False are effectively
 117 identical to ints 1 and 0, empty sequences are considered False, etc.
 118
 119 Nothing is done about Python exceptions currently, although it would be
 120 possible to capture the stack and expression just before the exception
 121 and build a robust and flexible error handler.  Because they are both
 122 just datastructures, you could immediately retry them under a debugger,
 123 or edit either or both of the stack and expression.  All state is in one
 124 or the other.
 125
 126 §.4.2 Literals and Simple Functions
 127
 128     joy? 1 2 3
 129           . 1 2 3
 130         1 . 2 3
 131       1 2 . 3
 132     1 2 3 .
 133
 134     1 2 3 <-top
 135
 136     joy? + +
 137     1 2 3 . + +
 138       1 5 . +
 139         6 .
 140
 141     6 <-top
 142
 143     joy? 7 *
 144       6 . 7 *
 145     6 7 . *
 146      42 .
 147
 148     42 <-top
 149
 150     joy?
 151
 152
 153 §.4.3 Combinators
 154
 155 The main loop is very simple as most of the action happens through what
 156 are called "combinators": functions which accept quoted programs on the
 157 stack and run them in various ways.  These combinators factor specific
 158 patterns that provide the effect of control-flow in other languages (such
 159 as ifte which is like if..then..else..)  Combinators receive the current
 160 expession in addition to the stack and return the next expression.  They
 161 work by changing the pending expression the interpreter is about to
 162 execute.  The combinators could work by making recursive calls to the
 163 interpreter and all intermediate state would be held in the call stack of
 164 the implementation language, in this joy implementation they work instead
 165 by changing the pending expression and intermediate state is put there.
 166
 167     joy? 23 [0 >] [dup --] while
 168
 169     ...
 170
 171     -> 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
 172
 173
 174 TODO:
 175
 176 §.4.4 Definitions and More Elaborate Functions
 177
 178 §.4.5 Programming and Metaprogramming
 179
 180 §.4.6 Refactoring
 181
 182
 183 §.5 This Implementation
 184
 185 Run with:
 186
 187     python -m joy
 188
 189 Thun
 190  |-- COPYING - license
 191  |-- README - this file
 192  |
 193  |-- archive - info on Joy
 194  |   |-- Joy-Programming.zip
 195  |   `-- README
 196  |
 197  |-- docs - Various Examples and Demos
 198  |   |-- * - Jupyter Notebooks on Thun and supporting modules
 199  |   `-- README - Table of Contents
 200  |
 201  |-- joy
 202  |   |-- joy.py - main loop, REPL
 203  |   |-- library.py - Functions, Combinators, Definitions
 204  |   |-- parser.py - convert text to Joy datastructures
 205  |   |
 206  |   `-- utils
 207  |       |-- pretty_print.py - convert Joy datastructures to text
 208  |       `-- stack.py - work with stacks
 209  |
 210  |-- thun - Experimental Prolog Code
 211  |   |-- compiler.pl - A start on a compiler for Prof. Wirth's RISC CPU
 212  |   `-- thun.pl - An interpreter in the Logical Paradigm, compiler.
 213  |
 214  `-- setup.py
 215
 216
 217
 218 §.6 References & Further Reading
 219
 220
 221 Wikipedia entry for Joy:
 222 https://en.wikipedia.org/wiki/Joy_%28programming_language%29
 223
 224
 225 Homepage at La Trobe University:
 226 http://www.latrobe.edu.au/humanities/research/research-projects/past-projects/joy-programming-language
 227
 228
 229
 230 --------------------------------------------------
 231
 232 Misc...
 233
 234 Stack based - literals (as functions) - functions - combinators -
 235 Refactoring and making new definitions - traces and comparing
 236 performance - metaprogramming as programming, even the lowly integer
 237 range function can be expressed in two phases: building a specialized
 238 program and then executing it with a combinator - ?Partial evaluation?
 239 - ?memoized dynamic dependency graphs? - algebra
 240