minor edits
This commit is contained in:
sforman
parent
45f00c8f2e
commit
f15eef1c56
|
|
@ -2,9 +2,7 @@
|
||||||
|
|
||||||
> Simple pleasures are the best.
|
> Simple pleasures are the best.
|
||||||
|
|
||||||
This interpreter written in Nim is part of the Thun project, which
|
This interpreter written in Nim is part of the Thun project.
|
||||||
includes interpreters written in Python and Prolog, and some explorations
|
|
||||||
towards compilers for Joy written in Prolog.
|
|
||||||
|
|
||||||
|
|
||||||
## Dependencies
|
## Dependencies
|
||||||
|
|
@ -35,5 +33,3 @@ compile the `joy` executable.
|
||||||
- `words` and `help`?
|
- `words` and `help`?
|
||||||
- How to integrate docs?
|
- How to integrate docs?
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,234 +1,40 @@
|
||||||
This is out of date. The Python implementation was the original one.
|
# Joy interpreter in Python
|
||||||
|
|
||||||
Thun
|
> Simple pleasures are the best.
|
||||||
|
|
||||||
A Dialect of Joy.
|
This interpreter written in Python is part of the Thun project.
|
||||||
|
|
||||||
v0.4.2
|
|
||||||
|
|
||||||
§.1 Introduction
|
|
||||||
|
|
||||||
Joy is a programming language created by Manfred von Thun that is easy to
|
|
||||||
use and understand and has many other nice properties. This project
|
|
||||||
implements interpreters for a dialect that attempts to stay very close to
|
|
||||||
the spirit of Joy but does not precisely match the behaviour of the
|
|
||||||
original version written in C.
|
|
||||||
|
|
||||||
The best source (no pun intended) for learning about Joy is the
|
|
||||||
information made available at the website of La Trobe University (see the
|
|
||||||
references section below for the URL) which contains source code for the
|
|
||||||
original C interpreter, Joy language source code for various functions,
|
|
||||||
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.
|
|
||||||
|
|
||||||
|
|
||||||
§.2 Installation
|
## Building
|
||||||
|
|
||||||
From PyPI in the usual way, e.g.:
|
To build an executable script just run:
|
||||||
|
|
||||||
pip install Thun
|
make
|
||||||
|
|
||||||
Or if you have downloaded the source, from the top directory:
|
This will copy the `implementations/defs.txt` file into the Python project and
|
||||||
|
splice it into the `joy.py` file to create the `joy` executable script.
|
||||||
|
|
||||||
python ./setup.py install
|
|
||||||
|
|
||||||
Or you can run the package directly from the top directory.
|
## Installation
|
||||||
|
|
||||||
To start a crude REPL:
|
I had the Python package set up to upload to PyPI as "Thun", but the
|
||||||
|
whole Python distribution story seems unsettled at the moment (2023) so
|
||||||
|
I've gone back to the *old ways*: there is a single script `joy.py`
|
||||||
|
that gets modified (``defs.txt`` is inserted) to create a `joy` script
|
||||||
|
that uses the "shebang" trick to pretend to be a binary. In other words,
|
||||||
|
run ``make`` and put the resulting ``joy`` script in your PATH, if that's
|
||||||
|
what you want to do. In a year or two the Python folks will have sorted
|
||||||
|
things out and we can go back to ``pip install Thun`` or whatever.
|
||||||
|
|
||||||
python -m joy
|
In the meantime, after `make` splices the `defs.txt` file into the `joy.py`
|
||||||
|
script to make the `joy` script you can start it as normal:
|
||||||
|
|
||||||
|
./joy
|
||||||
|
|
||||||
There is a "quiet" mode for e.g. using joy from a shell script:
|
There is a "quiet" mode for e.g. using joy from a shell script:
|
||||||
|
|
||||||
python -m joy -q
|
./joy -q
|
||||||
|
|
||||||
This supresses the initial banner output and the prompt text.
|
This suppresses the initial banner output and the prompt text.
|
||||||
|
|
||||||
|
|
||||||
§.3 Documentation
|
|
||||||
|
|
||||||
§.3.1 Jupyter Notebooks
|
|
||||||
|
|
||||||
The docs/ folder contains Jupyter notebooks, ... TODO
|
|
||||||
|
|
||||||
§.3.2 Sphinx Docs
|
|
||||||
|
|
||||||
Some of the documentation is in the form of ReST files
|
|
||||||
|
|
||||||
§.3.3 Building the Docs
|
|
||||||
|
|
||||||
Building the documentation is a little tricky at the moment. It involves
|
|
||||||
a makefile that uses nbconvert to generate ReST files from some of the
|
|
||||||
notebooks, copies those to the sphinx source dir, then builds the HTML
|
|
||||||
output using sphinx.
|
|
||||||
|
|
||||||
Get the dependencies for (re)building the docs:
|
|
||||||
|
|
||||||
pip install Thun[build-docs]
|
|
||||||
make docs
|
|
||||||
|
|
||||||
|
|
||||||
§.4 Basics of Joy
|
|
||||||
|
|
||||||
Joy is stack-based. There is a main stack that holds data items:
|
|
||||||
integers, floats, strings, functions, and sequences or quotes which hold
|
|
||||||
data items themselves.
|
|
||||||
|
|
||||||
23 1.8 'a string' "another" dup [21 18 /] [1 [2 [3]]]
|
|
||||||
|
|
||||||
A Joy expression is just a sequence (a.k.a. "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.
|
|
||||||
|
|
||||||
§.4.1 Python Semantics
|
|
||||||
|
|
||||||
In general, where otherwise unspecified, the semantics of Thun are that
|
|
||||||
of the underlying Python. That means, for example, that integers are
|
|
||||||
unbounded (whatever your machine can handle), strings cannot be added to
|
|
||||||
integers but can be multiplied, Boolean True and False are effectively
|
|
||||||
identical to ints 1 and 0, empty sequences are considered False, etc.
|
|
||||||
|
|
||||||
Nothing is done about Python exceptions currently, although it would be
|
|
||||||
possible to capture the stack and expression just before the exception
|
|
||||||
and build a robust and flexible error handler. Because they are both
|
|
||||||
just datastructures, you could immediately retry them under a debugger,
|
|
||||||
or edit either or both of the stack and expression. All state is in one
|
|
||||||
or the other.
|
|
||||||
|
|
||||||
§.4.2 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?
|
|
||||||
|
|
||||||
|
|
||||||
§.4.3 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
|
|
||||||
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
|
|
||||||
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.
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
|
|
||||||
TODO:
|
|
||||||
|
|
||||||
§.4.4 Definitions and More Elaborate Functions
|
|
||||||
|
|
||||||
§.4.5 Programming and Metaprogramming
|
|
||||||
|
|
||||||
§.4.6 Refactoring
|
|
||||||
|
|
||||||
|
|
||||||
§.5 This Implementation
|
|
||||||
|
|
||||||
Run with:
|
|
||||||
|
|
||||||
python -m joy
|
|
||||||
|
|
||||||
Thun
|
|
||||||
|-- COPYING - license
|
|
||||||
|-- README - this file
|
|
||||||
|
|
|
||||||
|-- archive - info on Joy
|
|
||||||
| |-- Joy-Programming.zip
|
|
||||||
| `-- README
|
|
||||||
|
|
|
||||||
|-- docs - Various Examples and Demos
|
|
||||||
| |-- * - Jupyter Notebooks on Thun and supporting modules
|
|
||||||
| `-- README - Table of Contents
|
|
||||||
|
|
|
||||||
|-- joy
|
|
||||||
| |-- joy.py - main loop, REPL
|
|
||||||
| |-- library.py - Functions, Combinators, Definitions
|
|
||||||
| |-- parser.py - convert text to Joy datastructures
|
|
||||||
| |
|
|
||||||
| `-- utils
|
|
||||||
| |-- pretty_print.py - convert Joy datastructures to text
|
|
||||||
| `-- stack.py - work with stacks
|
|
||||||
|
|
|
||||||
|-- thun - Experimental Prolog Code
|
|
||||||
| |-- compiler.pl - A start on a compiler for Prof. Wirth's RISC CPU
|
|
||||||
| `-- thun.pl - An interpreter in the Logical Paradigm, compiler.
|
|
||||||
|
|
|
||||||
`-- setup.py
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
§.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
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
--------------------------------------------------
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
Thun is free software: you can redistribute it and/or modify it under the
|
|
||||||
terms of the GNU General Public License as published by the Free Software
|
|
||||||
Foundation, either version 3 of the License, or (at your option) any
|
|
||||||
later version.
|
|
||||||
|
|
||||||
Thun is distributed in the hope that it will be useful, but WITHOUT ANY
|
|
||||||
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
|
|
||||||
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
|
|
||||||
details.
|
|
||||||
|
|
||||||
You should have received a copy of the GNU General Public License along
|
|
||||||
with Thun. If not see <http://www.gnu.org/licenses/>.
|
|
||||||
|
|
||||||
|
|
|
||||||
50
misc.txt
50
misc.txt
|
|
@ -1,13 +1,4 @@
|
||||||
|
|
||||||
(I had the Python package set up to upload to PyPI as "Thun", but the
|
|
||||||
whole Python distribution story seems unsettled at the moment (2023) so
|
|
||||||
I've gone back to the *old ways*: there is a single script ``joy.py``
|
|
||||||
that gets modified (``defs.txt`` is inserted) to create a ``joy`` script
|
|
||||||
that uses the "shebang" trick to pretend to be a binary. In other words,
|
|
||||||
run ``make`` and put the resulting ``joy`` script in your PATH, if that's
|
|
||||||
what you want to do. In a year or two the Python folks will have sorted
|
|
||||||
things out and we can go back to ``pip install Thun`` or whatever.)
|
|
||||||
|
|
||||||
|
|
||||||
nim cc \
|
nim cc \
|
||||||
-d:release \
|
-d:release \
|
||||||
|
|
@ -21,3 +12,44 @@ joy.nim
|
||||||
nim doc --project --index:on --git.url:"https://git.sr.ht/~sforman/Bliss" --git.commit:10b5651ed242fb16c29f2c1f7340d77f65926ca4 --outdir:htmldocs joy.nim
|
nim doc --project --index:on --git.url:"https://git.sr.ht/~sforman/Bliss" --git.commit:10b5651ed242fb16c29f2c1f7340d77f65926ca4 --outdir:htmldocs joy.nim
|
||||||
|
|
||||||
https://git.sr.ht/~sforman/Bliss/tree/10b5651ed242fb16c29f2c1f7340d77f65926ca4/item/types.nim#L26
|
https://git.sr.ht/~sforman/Bliss/tree/10b5651ed242fb16c29f2c1f7340d77f65926ca4/item/types.nim#L26
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
§.3.1 Jupyter Notebooks
|
||||||
|
|
||||||
|
The docs/ folder contains Jupyter notebooks, ... TODO
|
||||||
|
|
||||||
|
§.3.2 Sphinx Docs
|
||||||
|
|
||||||
|
Some of the documentation is in the form of ReST files
|
||||||
|
|
||||||
|
§.3.3 Building the Docs
|
||||||
|
|
||||||
|
Building the documentation is a little tricky at the moment. It involves
|
||||||
|
a makefile that uses nbconvert to generate ReST files from some of the
|
||||||
|
notebooks, copies those to the sphinx source dir, then builds the HTML
|
||||||
|
output using sphinx.
|
||||||
|
|
||||||
|
Get the dependencies for (re)building the docs:
|
||||||
|
|
||||||
|
pip install Thun[build-docs]
|
||||||
|
make docs
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Nothing is done about Python exceptions currently, although it would be
|
||||||
|
possible to capture the stack and expression just before the exception
|
||||||
|
and build a robust and flexible error handler. Because they are both
|
||||||
|
just datastructures, you could immediately retry them under a debugger,
|
||||||
|
or edit either or both of the stack and expression. All state is in one
|
||||||
|
or the other.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue