• R/O
  • HTTP
  • SSH
  • HTTPS

Thun: Commit

Interpreter and library.


Commit MetaInfo

Révisiona0374c5734d50b8887a043a631ca8601a8662ecf (tree)
l'heure2022-04-05 00:01:51
AuteurSimon Forman <sforman@hush...>
CommiterSimon Forman

Message de Log

Start a per-project README for Python.

Change Summary

Modification

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