From f15eef1c56c47d1ee19574f500575273c0b5783e Mon Sep 17 00:00:00 2001 From: sforman Date: Mon, 31 Jul 2023 12:08:39 -0700 Subject: [PATCH] minor edits --- implementations/Nim/README.md | 6 +- implementations/Python/README.md | 240 +++---------------------------- misc.txt | 50 +++++-- 3 files changed, 65 insertions(+), 231 deletions(-) diff --git a/implementations/Nim/README.md b/implementations/Nim/README.md index be8dea1..960ca8d 100644 --- a/implementations/Nim/README.md +++ b/implementations/Nim/README.md @@ -2,9 +2,7 @@ > Simple pleasures are the best. -This interpreter written in Nim is part of the Thun project, which -includes interpreters written in Python and Prolog, and some explorations -towards compilers for Joy written in Prolog. +This interpreter written in Nim is part of the Thun project. ## Dependencies @@ -35,5 +33,3 @@ compile the `joy` executable. - `words` and `help`? - How to integrate docs? - - diff --git a/implementations/Python/README.md b/implementations/Python/README.md index 50a4949..da69e3d 100644 --- a/implementations/Python/README.md +++ b/implementations/Python/README.md @@ -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. - -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. +This interpreter written in Python is part of the Thun project. -§.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: - 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 . - diff --git a/misc.txt b/misc.txt index 4e941f8..6adbd83 100644 --- a/misc.txt +++ b/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 \ -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 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. + +