README

   1
   2
   3                 Thun
   4
   5   Dialects of Joy in Python.
   6
   7                v0.4.0
   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
  68 §.3 Documentation
  69
  70 §.3.1 Jupyter Notebooks
  71
  72 The docs/ folder contains Jupyter notebooks, ... TODO
  73
  74 §.3.2 Sphinx Docs
  75
  76 Some of the documentation is in the form of ReST files
  77
  78 §.3.3 Building the Docs
  79
  80 Building the documentation is a little tricky at the moment.  It involves
  81 a makefile that uses nbconvert to generate ReST files from some of the
  82 notebooks, copies those to the sphinx source dir, then builds the HTML
  83 output using sphinx.
  84
  85 Get the dependencies for (re)building the docs:
  86
  87     pip install Thun[build-docs]
  88     make docs
  89
  90
  91 §.4 Basics of Joy
  92
  93 Joy is stack-based.  There is a main stack that holds data items:
  94 integers, floats, strings, functions, and sequences or quotes which hold
  95 data items themselves.
  96
  97     23 1.8 'a string' "another" dup [21 18 /] [1 [2 [3]]]
  98
  99 A Joy expression is just a sequence (a.k.a. "list") of items.  Sequences
 100 intended as programs are called "quoted programs".  Evaluation proceeds
 101 by iterating through the terms in the expression, putting all literals
 102 onto the main stack and executing functions as they are encountered.
 103 Functions receive the current stack and return the next stack.
 104
 105 §.4.1 Python Semantics
 106
 107 In general, where otherwise unspecified, the semantics of Thun are that
 108 of the underlying Python. That means, for example, that integers are
 109 unbounded (whatever your machine can handle), strings cannot be added to
 110 integers but can be multiplied, Boolean True and False are effectively
 111 identical to ints 1 and 0, empty sequences are considered False, etc.
 112
 113 Nothing is done about Python exceptions currently, although it would be
 114 possible to capture the stack and expression just before the exception
 115 and build a robust and flexible error handler.  Because they are both
 116 just datastructures, you could immediately retry them under a debugger,
 117 or edit either or both of the stack and expression.  All state is in one
 118 or the other.
 119
 120 §.4.2 Literals and Simple Functions
 121
 122     joy? 1 2 3
 123           . 1 2 3
 124         1 . 2 3
 125       1 2 . 3
 126     1 2 3 .
 127
 128     1 2 3 <-top
 129
 130     joy? + +
 131     1 2 3 . + +
 132       1 5 . +
 133         6 .
 134
 135     6 <-top
 136
 137     joy? 7 *
 138       6 . 7 *
 139     6 7 . *
 140      42 .
 141
 142     42 <-top
 143
 144     joy?
 145
 146
 147 §.4.3 Combinators
 148
 149 The main loop is very simple as most of the action happens through what
 150 are called "combinators": functions which accept quoted programs on the
 151 stack and run them in various ways.  These combinators factor specific
 152 patterns that provide the effect of control-flow in other languages (such
 153 as ifte which is like if..then..else..)  Combinators receive the current
 154 expession in addition to the stack and return the next expression.  They
 155 work by changing the pending expression the interpreter is about to
 156 execute.  The combinators could work by making recursive calls to the
 157 interpreter and all intermediate state would be held in the call stack of
 158 the implementation language, in this joy implementation they work instead
 159 by changing the pending expression and intermediate state is put there.
 160
 161     joy? 23 [0 >] [dup --] while
 162
 163     ...
 164
 165     -> 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
 166
 167
 168 TODO:
 169
 170 §.4.4 Definitions and More Elaborate Functions
 171
 172 §.4.5 Programming and Metaprogramming
 173
 174 §.4.6 Refactoring
 175
 176
 177 §.5 This Implementation
 178
 179 Run with:
 180
 181     python -m joy
 182
 183 Thun
 184  |-- COPYING - license
 185  |-- README - this file
 186  |
 187  |-- archive - info on Joy
 188  |   |-- Joy-Programming.zip
 189  |   `-- README
 190  |
 191  |-- docs - Various Examples and Demos
 192  |   |-- * - Jupyter Notebooks on Thun and supporting modules
 193  |   `-- README - Table of Contents
 194  |
 195  |-- joy
 196  |   |-- joy.py - main loop, REPL
 197  |   |-- library.py - Functions, Combinators, Definitions
 198  |   |-- parser.py - convert text to Joy datastructures
 199  |   |
 200  |   `-- utils
 201  |       |-- pretty_print.py - convert Joy datastructures to text
 202  |       `-- stack.py - work with stacks
 203  |
 204  |-- thun - Experimental Prolog Code
 205  |   |-- compiler.pl - A start on a compiler for Prof. Wirth's RISC CPU
 206  |   `-- thun.pl - An interpreter in the Logical Paradigm, compiler.
 207  |
 208  `-- setup.py
 209
 210
 211
 212 §.6 References & Further Reading
 213
 214
 215 Wikipedia entry for Joy:
 216 https://en.wikipedia.org/wiki/Joy_%28programming_language%29
 217
 218
 219 Homepage at La Trobe University:
 220 http://www.latrobe.edu.au/humanities/research/research-projects/past-projects/joy-programming-language
 221
 222
 223
 224 --------------------------------------------------
 225
 226 Misc...
 227
 228 Stack based - literals (as functions) - functions - combinators -
 229 Refactoring and making new definitions - traces and comparing
 230 performance - metaprogramming as programming, even the lowly integer
 231 range function can be expressed in two phases: building a specialized
 232 program and then executing it with a combinator - ?Partial evaluation?
 233 - ?memoized dynamic dependency graphs? - algebra
 234