sforman
/
Thun
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Minor updates to README file. 

Removed setup.py until Python folks stabilize packaging and
distribution.  Just put the joy script in your PATH, eh?
This commit is contained in:
Simon Forman 2023-02-15 10:05:25 -08:00
parent aee4365929
commit 610de03e0b
3 changed files with 187 additions and 184 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

165
README.md
View File

@ -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

148
docs/html/index.html
View File

@ -17,9 +17,10 @@ programming language created by Manfred von Thun that is easy to use and
understand and has many other nice properties. <strong>Thun</strong> 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.</p>
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).</p>
<p>Joy is:</p>
<ul>
<li><a href="https://en.wikipedia.org/wiki/Purely_functional_programming">Purely Functional</a></li>
@ -42,20 +43,12 @@ interesting aspects. It's quite a treasure trove.</p>
<a href="https://www.kevinalbrecht.com/code/joy-mirror/">(Kevin Albrecht's mirror)</a></li>
<li><a href="https://web.archive.org/web/20220411010035/https://joypy.osdn.io/">The original Thun/Joypy site</a></li>
</ul>
<h2>Differences of Thun to Joy</h2>
<p>Thun currently only uses four datatypes:</p>
<ul>
<li>Integers, these are signed and are not bounded by machine word
length (they are
<a href="https://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic">bignums</a>.)</li>
<li>Boolean values <code>true</code> and <code>false</code>.</li>
<li>Lists quoted in <strong>[</strong> and <strong>]</strong> brackets.</li>
<li>Symbols (names).</li>
</ul>
<p>Thun works by <a href="https://en.wikipedia.org/wiki/Continuation-passing_style">Continuation Passing Style</a>.</p>
<p>Something else I can't remember at the mo'.</p>
<h2>Example Code</h2>
<p>Here is an example of Joy code:</p>
<p>Here is an example of Joy code. This function <code>square_spiral</code> 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 <a href="https://en.wikipedia.org/wiki/Ulam_spiral">Ulam Spiral</a>).
For more information see <a href="/notebooks/Square_Spiral.html">Square Spiral Example Joy Code</a>.</p>
<pre><code>square_spiral [_p] [_then] [_else] ifte
_p [_p0] [_p1] &amp;&amp;
@ -65,12 +58,7 @@ _p1 [&lt;&gt;] [pop !-] ||
_then [ !-] [[++]] [[--]] ifte dip
_else [pop !-] [--] [++] ifte
</code></pre>
<p>It might seem unreadable but with a little familiarity it becomes just as legible as any other notation.</p>
<p>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
<a href="https://en.wikipedia.org/wiki/Ulam_spiral">Ulam Spiral</a>
). For more information see <a href="/notebooks/Square_Spiral.html">Square Spiral Example Joy Code</a></p>
<p>It might seem unreadable but with familiarity it becomes as legible as any other notation.</p>
<h2>Project Hosted on <a href="https://osdn.net/projects/joypy/">OSDN</a></h2>
<ul>
<li><a href="https://osdn.net/projects/joypy/scm/git/Thun/">Source Repository</a>
@ -80,63 +68,101 @@ coordinate pair in a square spiral (like the kind used to construct an
<li><a href="https://osdn.net/projects/joypy/forums/">Forums</a></li>
<li><a href="https://osdn.net/projects/joypy/lists/">Mailing list</a></li>
</ul>
<h2>Directory structure</h2>
<pre><code>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
</code></pre>
<h2>Documentation</h2>
<p>This document describes Joy in a general way below, however most of the
documentation is in the form of <a href="/notebooks/index.html">Jupyter Notebooks</a>
that go into more detail.</p>
<h3><a href="/notebooks/index.html">Jupyter Notebooks</a></h3>
<p>There's also a <a href="/FuncRef.html">Function Reference</a> that lists each
function and combinator by name and gives a brief description. (It's
usually out of date, I'm working on it.)</p>
<h3><a href="/FuncRef.html">Function Reference</a></h3>
<h3>Building the Docs</h3>
<p>Run <code>make</code> in the <code>docs</code> directory. (This is a lie, it's more complex than
that. Really you need to run (GNU) make in the <code>docs/notebooks</code> and
<code>docs/reference</code> dirs first, <em>then</em> run <code>make</code> in the <code>docs</code> directory.)</p>
<h2>Directory structure</h2>
<pre><code>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
</code></pre>
<h2>Installation</h2>
<p>Clone the repo and follow the instructions in the individual <code>implementations</code> directories.</p>
<p>Clone the repo and follow the instructions in the individual
<code>implementations</code> directories. There isn't really any installation. You
can put the binaries in your <code>PATH</code>.</p>
<p>(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 <em>old ways</em>: there is a single script <code>joy.py</code>
that gets modified (<code>defs.txt</code> is inserted) to create a <code>joy</code> script
that uses the "shebang" trick to pretend to be a binary. In other words,
run <code>make</code> and put the resulting <code>joy</code> 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 <code>pip install Thun</code> or whatever.)</p>
<h2>Basics of Joy</h2>
<p>The original Joy has several datatypes (such as strings and sets)
but the Thun dialect currently only uses four:</p>
<ul>
<li>Integers, signed and unbounded by machine word length (they are
<a href="https://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic">bignums</a>.)</li>
<li>Boolean values <code>true</code> and <code>false</code>.</li>
<li>Lists quoted in <strong>[</strong> and <strong>]</strong> brackets.</li>
<li>Symbols (names).</li>
</ul>
<p>Joy is built around three things: a <strong>stack</strong> of data items, an <strong>expression</strong>
representing a program to evaluate, and a <strong>dictionary</strong> of named functions.</p>
<h3>Stack</h3>
<p>Joy is <a href="https://en.wikipedia.org/wiki/Stack-oriented_programming_language">stack-based</a>.
There is a single main <strong>stack</strong> that holds data items, which can be integers, bools,
symbols (names), or sequences of data items enclosed in square brackets (<code>[</code> or <code>]</code>).</p>
<pre><code>23 dup [21 18 add] true false [1 [2 [3]]] cons
</code></pre>
<h3>Expression</h3>
<p>A Joy <strong>expression</strong> 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.</p>
<p>The <strong>dictionary</strong> 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.</p>
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.</p>
<h3>Dictionary</h3>
<p>The <strong>dictionary</strong> 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.</p>
<h3>Interpreter</h3>
<p>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.</p>
<p>All control flow works by
<a href="https://en.wikipedia.org/wiki/Continuation-passing_style">Continuation Passing Style</a>.
<strong>Combinators</strong> (see below) alter control flow by prepending quoted programs to the pending
expression (aka "continuation".)</p>
<p><img alt="joy_interpreter_flowchart.svg" src="/joy_interpreter_flowchart.svg"></p>
<h3>Stack / Quote / List / Sequence</h3>
<h2>Stack / Quote / List / Sequence</h2>
<p>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.</p>
</blockquote>
<p>From <a href="http://archive.vector.org.uk/art10000350">"A Conversation with Manfred von Thun" w/ Stevan Apter</a></p>
<hr>
<p>From here it kinda falls apart...</p>
<h3>Literals and Simple Functions</h3>
<p>TODO</p>
<h3>Combinators</h3>
@ -171,7 +199,7 @@ by changing the pending expression and intermediate state is put there.)</p>
23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
</code></pre>
<hr>
<p>Copyright © 2014-2022 Simon Forman</p>
<p>Copyright © 2014 - 2023 Simon Forman</p>
<p>This file is part of Thun</p>
<p>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

58
implementations/Python/setup.py
View File

@ -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 <http://www.gnu.org/licenses/>.
#
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',
],
}
)