README

   1
   2
   3             Thun
   4
   5   A dialect of Joy in Python.
   6
   7            v0.2.0
   8
   9
  10 --------------------------------------------------
  11
  12
  13 Copyright © 2014-2018 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 later
  20 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 FOR A
  24 PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  25
  26 You should have received a copy of the GNU General Public License along with
  27 Thun.  If not see <http://www.gnu.org/licenses/>.
  28
  29
  30 --------------------------------------------------
  31
  32
  33 §.1 Introduction
  34
  35 Joy is a programming language created by Manfred von Thun that is easy to
  36 use and understand and has many other nice properties.  This Python
  37 package implements an interpreter for a dialect of Joy that attempts to
  38 stay very close to the spirit of Joy but does not precisely match the
  39 behaviour of the original version(s) written in C.  The main difference
  40 between Thun and the originals, other than being written in Python, is
  41 that it works by the "Continuation-Passing Style".
  42
  43 As I study Joy I find that it is very aptly named.  It is clear, concise,
  44 and ameniable to advanced techniques for constructing bug-free software.
  45
  46 Developed by Manfred von Thun, don't know much about him, not much on the
  47 web about Joy and von Thun (Von Thun?) See references below.
  48
  49 Because it has desirable properties (concise, highly factored) the
  50 programming process changes, the ratio of designing to writing code
  51 shifts in favor of design.  The documentation becomes extensive while the
  52 code shrinks to stable bodies of small well-factored incantations that
  53 are highly expressive, much like mathematical papers consist of large
  54 bodies of exposition interlaced with mathematical formula that concisely
  55 and precisely express the meaning of the text.
  56
  57 The time and attention of the programmer shifts from thinking about the
  58 language to thinking in the language, and the development process feels
  59 more like deriving mathematical truths than like writing ad-hoc
  60 solutions.
  61
  62 I hope that this package is useful in the sense that it provides an
  63 additional joy interpreter (the binary in the archive from La Trobe seems
  64 to run just fine on my modern Linux machine!)  But I also hope that you
  65 can read and understand the Python code and play with the implementation
  66 itself.
  67
  68 The best source (no pun intended) for learning about Joy is the
  69 information made available at the website of La Trobe University (see the
  70 references section below for the URL) which contains source code for the
  71 original C interpreter, Joy language source code for various functions,
  72 and a great deal of fascinating material mostly written by Von Thun on
  73 Joy and its deeper facets as well as how to program in it and several
  74 interesting aspects.  It's quite a treasure trove.
  75
  76
  77 §.2 Installation
  78
  79 From PyPI in the usual way, e.g.:
  80
  81     pip install Thun
  82
  83 Or if you have downloaded the source, from the top directory:
  84
  85     python ./setup.py install
  86
  87 Or you can run the package from the top directory.  To start a crude REPL:
  88
  89     python -m joy
  90
  91
  92 §.3 Documentation
  93
  94 The docs/ folder contains Jupyter notebooks, ... TODO
  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
 184 §.5 This Implementation
 185
 186 Run with:
 187
 188     python -m joy
 189
 190 joypy
 191  |-- COPYING - license
 192  |-- README - this file
 193  |
 194  |-- archive - info on Joy
 195  |   |-- Joy-Programming.zip
 196  |   `-- README
 197  |
 198  |-- docs - Various Examples and Demos
 199  |   |-- * - Jupyter Notebooks on Thun and supporting modules
 200  |   `-- README - Table of Contents
 201  |
 202  |-- joy
 203  |   |-- joy.py - main loop, REPL
 204  |   |-- library.py - Functions, Combinators, Definitions
 205  |   |-- parser.py - convert text to Joy datastructures
 206  |   |
 207  |   `-- utils
 208  |       |-- pretty_print.py - convert Joy datastructures to text
 209  |       `-- stack.py - work with stacks
 210  |
 211  `-- setup.py
 212
 213
 214
 215 §.6 References & Further Reading
 216
 217
 218 Wikipedia entry for Joy:
 219 https://en.wikipedia.org/wiki/Joy_%28programming_language%29
 220
 221
 222 Homepage at La Trobe University:
 223 http://www.latrobe.edu.au/humanities/research/research-projects/past-projects/joy-programming-language
 224
 225
 226
 227 --------------------------------------------------
 228
 229 Misc...
 230
 231 Stack based - literals (as functions) - functions - combinators -
 232 Refactoring and making new definitions - traces and comparing
 233 performance - metaprogramming as programming, even the lowly integer
 234 range function can be expressed in two phases: building a specialized
 235 program and then executing it with a combinator - ?Partial evaluation?
 236 - ?memoized dynamic dependency graphs? - algebra
 237