From 610de03e0b9e936d9ee1fd0eb2342a877776a178 Mon Sep 17 00:00:00 2001 From: Simon Forman Date: Wed, 15 Feb 2023 10:05:25 -0800 Subject: [PATCH] Minor updates to README file. Removed setup.py until Python folks stabilize packaging and distribution. Just put the joy script in your PATH, eh? --- README.md | 165 +++++++++++++++++++------------- docs/html/index.html | 148 ++++++++++++++++------------ implementations/Python/setup.py | 58 ----------- 3 files changed, 187 insertions(+), 184 deletions(-) delete mode 100755 implementations/Python/setup.py diff --git a/README.md b/README.md index 3103c06..c0d9c42 100644 --- a/README.md +++ b/README.md @@ -11,9 +11,10 @@ programming language created by Manfred von Thun that is easy to use and understand and has many other nice properties. **Thun** is a dialect of Joy 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. It -started as a Python project called Joypy, but after someone claimed the -name on PyPI before me I renamed it to Thun in honor of Manfred Von Thun -who created Joy. +started as a Python project called "Joypy", but after someone claimed that +name on PyPI before me I renamed it to Thun in honor of Manfred Von Thun. +Now there are interpreters implemented in several additional languages +(C, Nim, Prolog, Rust). Joy is: @@ -38,25 +39,13 @@ interesting aspects. It's quite a treasure trove. * [The original Thun/Joypy site](https://web.archive.org/web/20220411010035/https://joypy.osdn.io/) -## Differences of Thun to Joy - -Thun currently only uses four datatypes: - -* Integers, these are signed and are not bounded by machine word - length (they are - [bignums](https://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic).) -* Boolean values ``true`` and ``false``. -* Lists quoted in **[** and **]** brackets. -* Symbols (names). - -Thun works by [Continuation Passing Style](https://en.wikipedia.org/wiki/Continuation-passing_style). - -Something else I can't remember at the mo'. - - ## Example Code -Here is an example of Joy code: +Here is an example of Joy code. This function `square_spiral` accepts +two integers and increments or decrements one of them such that the new +pair of numbers is the next coordinate pair in a square spiral (like the +kind used to construct an [Ulam Spiral](https://en.wikipedia.org/wiki/Ulam_spiral)). +For more information see [Square Spiral Example Joy Code](/notebooks/Square_Spiral.html). square_spiral [_p] [_then] [_else] ifte @@ -67,13 +56,8 @@ Here is an example of Joy code: _then [ !-] [[++]] [[--]] ifte dip _else [pop !-] [--] [++] ifte -It might seem unreadable but with a little familiarity it becomes just as legible as any other notation. +It might seem unreadable but with familiarity it becomes as legible as any other notation. -This function accepts two integers on the stack and increments or -decrements one of them such that the new pair of numbers is the next -coordinate pair in a square spiral (like the kind used to construct an -[Ulam Spiral](https://en.wikipedia.org/wiki/Ulam_spiral) -). For more information see [Square Spiral Example Joy Code](/notebooks/Square_Spiral.html) ## Project Hosted on [OSDN](https://osdn.net/projects/joypy/) @@ -86,43 +70,22 @@ coordinate pair in a square spiral (like the kind used to construct an * [Mailing list](https://osdn.net/projects/joypy/lists/) -## Directory structure - - Thun - | - |-- LICENSE - GPLv3 - |-- README.md - this file - | - |-- archive - | |-- Joy-Programming.zip - | `-- README - | - |-- docs - | |-- Makefile - Generate https://joypy.osdn.io/ site. - | |-- notebooks - Jupyter Notebooks and supporting modules - | |-- reference - Docs for each function. - | |-- dep-graphs - Generated dependency graphs. - | `-- README - Table of Contents - | - `-- implementations - | - |-- Nim - interpreter - | - |-- Prolog - interpreter - | type inference - | work-in-progress compiler - | - |-- Python - interpreter - | - `-- defs.txt - common Joy definitions for all interpreters - - ## Documentation +This document describes Joy in a general way below, however most of the +documentation is in the form of [Jupyter Notebooks](/notebooks/index.html) +that go into more detail. + ### [Jupyter Notebooks](/notebooks/index.html) +There's also a [Function Reference](/FuncRef.html) that lists each +function and combinator by name and gives a brief description. (It's +usually out of date, I'm working on it.) + ### [Function Reference](/FuncRef.html) + + ### Building the Docs Run `make` in the `docs` directory. (This is a lie, it's more complex than @@ -130,38 +93,106 @@ that. Really you need to run (GNU) make in the `docs/notebooks` and `docs/reference` dirs first, _then_ run `make` in the `docs` directory.) +## Directory structure + Thun + |-- LICENSE - GPLv3 + |-- README.md - this file + | + |-- archive + | |-- Joy-Programming.zip + | `-- README + | + |-- docs + | |-- dep-graphs - Generated dependency graphs. + | |-- html - Generated HTML docs. + | |-- notebooks - Jupyter Notebooks and supporting modules + | `-- reference - Docs for each function. + | + |-- implementations + | |-- defs.txt - common Joy definitions for all interpreters + | |-- C - interpreter + | |-- GNUProlog - interpreter + | type inference + | work-in-progress compiler + | |-- Nim - interpreter + | |-- Ocaml - work-in-progress interpreter + | `-- Python - interpreter + | + `-- joy_code - Source code written in Joy. + `-- bigints + `-- bigints.joy + + ## Installation -Clone the repo and follow the instructions in the individual `implementations` directories. +Clone the repo and follow the instructions in the individual +`implementations` directories. There isn't really any installation. You +can put the binaries in your ``PATH``. + +(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.) ## Basics of Joy +The original Joy has several datatypes (such as strings and sets) +but the Thun dialect currently only uses four: + +* Integers, signed and unbounded by machine word length (they are + [bignums](https://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic).) +* Boolean values ``true`` and ``false``. +* Lists quoted in **[** and **]** brackets. +* Symbols (names). + Joy is built around three things: a __stack__ of data items, an __expression__ representing a program to evaluate, and a __dictionary__ of named functions. +### Stack + Joy is [stack-based](https://en.wikipedia.org/wiki/Stack-oriented_programming_language). There is a single main __stack__ that holds data items, which can be integers, bools, symbols (names), or sequences of data items enclosed in square brackets (`[` or `]`). 23 dup [21 18 add] true false [1 [2 [3]]] cons +### Expression + A Joy __expression__ is just a sequence or list of items. Sequences intended as programs are called "quoted programs". Evaluation proceeds -by iterating through the terms in an expression putting all literals (integers, bools, or lists) -onto the main stack and executing functions named by symbols as they are encountered. -Functions receive the current stack, expression, and dictionary and return the next stack. +by iterating through the terms in an expression putting all literals +(integers, bools, or lists) onto the main stack and executing functions +named by symbols as they are encountered. Functions receive the current +stack, expression, and dictionary and return the next stack, expression, +and dictionary. -The __dictionary__ associates symbols (strings) with Joy expressions that define the -available functions of the Joy system. Together the stack, expression, and dictionary -are the entire state of the Joy interpreter. +### Dictionary + +The __dictionary__ associates symbols (names) with Joy expressions that +define the available functions of the Joy system. Together the stack, +expression, and dictionary are the entire state of the Joy interpreter. ### Interpreter +The Joy interpreter is extrememly simple. It accepts a stack, an +expression, and a dictionary, and it iterates through the expression +putting values onto the stack and delegating execution to functions which +it looks up in the dictionary. + +All control flow works by +[Continuation Passing Style](https://en.wikipedia.org/wiki/Continuation-passing_style). +__Combinators__ (see below) alter control flow by prepending quoted programs to the pending +expression (aka "continuation".) + ![joy_interpreter_flowchart.svg](/joy_interpreter_flowchart.svg) -### Stack / Quote / List / Sequence +## Stack / Quote / List / Sequence When talking about Joy we use the terms "stack", "quote", "sequence", "list", and others to mean the same thing: a simple linear datatype that @@ -181,7 +212,9 @@ values from (at least) one end. From ["A Conversation with Manfred von Thun" w/ Stevan Apter](http://archive.vector.org.uk/art10000350) +------------------------------- +From here it kinda falls apart... ### Literals and Simple Functions @@ -209,7 +242,7 @@ by changing the pending expression and intermediate state is put there.) -------------------------------------------------- -Copyright © 2014-2022 Simon Forman +Copyright © 2014 - 2023 Simon Forman This file is part of Thun diff --git a/docs/html/index.html b/docs/html/index.html index ed60d49..02f4c07 100644 --- a/docs/html/index.html +++ b/docs/html/index.html @@ -17,9 +17,10 @@ programming language created by Manfred von Thun that is easy to use and understand and has many other nice properties. Thun is a dialect of Joy 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. It -started as a Python project called Joypy, but after someone claimed the -name on PyPI before me I renamed it to Thun in honor of Manfred Von Thun -who created Joy.

+started as a Python project called "Joypy", but after someone claimed that +name on PyPI before me I renamed it to Thun in honor of Manfred Von Thun. +Now there are interpreters implemented in several additional languages +(C, Nim, Prolog, Rust).

Joy is:

-

Differences of Thun to Joy

-

Thun currently only uses four datatypes:

- -

Thun works by Continuation Passing Style.

-

Something else I can't remember at the mo'.

Example Code

-

Here is an example of Joy code:

+

Here is an example of Joy code. This function square_spiral accepts +two integers and increments or decrements one of them such that the new +pair of numbers is the next coordinate pair in a square spiral (like the +kind used to construct an Ulam Spiral). +For more information see Square Spiral Example Joy Code.

square_spiral [_p] [_then] [_else] ifte
 
 _p  [_p0] [_p1] &&
@@ -65,12 +58,7 @@ _p1 [<>] [pop !-] ||
 _then [    !-] [[++]] [[--]] ifte dip
 _else [pop !-]  [--]   [++]  ifte
-

It might seem unreadable but with a little familiarity it becomes just as legible as any other notation.

-

This function accepts two integers on the stack and increments or -decrements one of them such that the new pair of numbers is the next -coordinate pair in a square spiral (like the kind used to construct an -Ulam Spiral -). For more information see Square Spiral Example Joy Code

+

It might seem unreadable but with familiarity it becomes as legible as any other notation.

Project Hosted on OSDN

-

Directory structure

-
Thun
- |
- |-- LICENSE - GPLv3
- |-- README.md - this file
- |
- |-- archive
- |   |-- Joy-Programming.zip
- |   `-- README
- |
- |-- docs
- |   |-- Makefile - Generate https://joypy.osdn.io/ site.
- |   |-- notebooks - Jupyter Notebooks and supporting modules
- |   |-- reference - Docs for each function.
- |   |-- dep-graphs - Generated dependency graphs.
- |   `-- README - Table of Contents
- |
- `-- implementations
-     |
-     |-- Nim - interpreter
-     |
-     |-- Prolog - interpreter
-     |            type inference
-     |            work-in-progress compiler
-     |
-     |-- Python - interpreter
-     |
-     `-- defs.txt - common Joy definitions for all interpreters
-

Documentation

+

This document describes Joy in a general way below, however most of the +documentation is in the form of Jupyter Notebooks +that go into more detail.

Jupyter Notebooks

+

There's also a Function Reference that lists each +function and combinator by name and gives a brief description. (It's +usually out of date, I'm working on it.)

Function Reference

Building the Docs

Run make in the docs directory. (This is a lie, it's more complex than that. Really you need to run (GNU) make in the docs/notebooks and docs/reference dirs first, then run make in the docs directory.)

+

Directory structure

+
Thun
+|-- LICENSE - GPLv3
+|-- README.md - this file
+|
+|-- archive
+|   |-- Joy-Programming.zip
+|   `-- README
+|
+|-- docs
+|   |-- dep-graphs - Generated dependency graphs.
+|   |-- html - Generated HTML docs.
+|   |-- notebooks - Jupyter Notebooks and supporting modules
+|   `-- reference - Docs for each function.
+|
+|-- implementations
+|   |-- defs.txt - common Joy definitions for all interpreters
+|   |-- C - interpreter
+|   |-- GNUProlog - interpreter
+    |               type inference
+    |               work-in-progress compiler
+|   |-- Nim - interpreter
+|   |-- Ocaml - work-in-progress interpreter
+|   `-- Python - interpreter
+|
+`-- joy_code - Source code written in Joy.
+    `-- bigints
+        `-- bigints.joy
+

Installation

-

Clone the repo and follow the instructions in the individual implementations directories.

+

Clone the repo and follow the instructions in the individual +implementations directories. There isn't really any installation. You +can put the binaries in your PATH.

+

(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.)

Basics of Joy

+

The original Joy has several datatypes (such as strings and sets) +but the Thun dialect currently only uses four:

+

Joy is built around three things: a stack of data items, an expression representing a program to evaluate, and a dictionary of named functions.

+

Stack

Joy is stack-based. There is a single main stack that holds data items, which can be integers, bools, symbols (names), or sequences of data items enclosed in square brackets ([ or ]).

23 dup [21 18 add] true false [1 [2 [3]]] cons
+

Expression

A Joy expression is just a sequence or list of items. Sequences intended as programs are called "quoted programs". Evaluation proceeds -by iterating through the terms in an expression putting all literals (integers, bools, or lists) -onto the main stack and executing functions named by symbols as they are encountered. -Functions receive the current stack, expression, and dictionary and return the next stack.

-

The dictionary associates symbols (strings) with Joy expressions that define the -available functions of the Joy system. Together the stack, expression, and dictionary -are the entire state of the Joy interpreter.

+by iterating through the terms in an expression putting all literals +(integers, bools, or lists) onto the main stack and executing functions +named by symbols as they are encountered. Functions receive the current +stack, expression, and dictionary and return the next stack, expression, +and dictionary.

+

Dictionary

+

The dictionary associates symbols (names) with Joy expressions that +define the available functions of the Joy system. Together the stack, +expression, and dictionary are the entire state of the Joy interpreter.

Interpreter

+

The Joy interpreter is extrememly simple. It accepts a stack, an +expression, and a dictionary, and it iterates through the expression +putting values onto the stack and delegating execution to functions which +it looks up in the dictionary.

+

All control flow works by +Continuation Passing Style. +Combinators (see below) alter control flow by prepending quoted programs to the pending +expression (aka "continuation".)

joy_interpreter_flowchart.svg

-

Stack / Quote / List / Sequence

+

Stack / Quote / List / Sequence

When talking about Joy we use the terms "stack", "quote", "sequence", "list", and others to mean the same thing: a simple linear datatype that permits certain operations such as iterating and pushing and popping @@ -153,6 +179,8 @@ them being pushed onto the stack. But I also call [London Paris] a list. So, [dup *] is a quotation but not a list.

From "A Conversation with Manfred von Thun" w/ Stevan Apter

+
+

From here it kinda falls apart...

Literals and Simple Functions

TODO

Combinators

@@ -171,7 +199,7 @@ by changing the pending expression and intermediate state is put there.)

23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
-

Copyright © 2014-2022 Simon Forman

+

Copyright © 2014 - 2023 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 diff --git a/implementations/Python/setup.py b/implementations/Python/setup.py deleted file mode 100755 index f843ee0..0000000 --- a/implementations/Python/setup.py +++ /dev/null @@ -1,58 +0,0 @@ -#!/usr/bin/env python -# -*- coding: utf-8 -*- -# -# Copyright © 2014, 2015, 2017, 2019 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 . -# -from setuptools import setup -from textwrap import dedent - - -setup( - name='Thun', - version='0.5.1', - description='Python Implementation of Joy', - long_description=dedent('''\ - Joy is a programming language created by Manfred von Thun that is easy to - use and understand and has many other nice properties. This Python - package implements an interpreter for a dialect of Joy 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.'''), - long_description_content_type='text/plain', - author='Simon Forman', - author_email='sforman@hushmail.com', - url='https://joypy.osdn.io', - license='GPLv3+', - packages=['joy', 'joy.utils'], - package_data={ - 'joy': ['defs.txt'], - }, - classifiers=[ - 'Development Status :: 4 - Beta', - 'License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)', - 'Programming Language :: Python :: 3', - 'Programming Language :: Other', - 'Topic :: Software Development :: Interpreters', - ], - extras_require={ - 'build-docs': [ - 'sphinx', - 'ipython', - 'nbconvert', - ], - } - )