docs/sphinx_docs/index.rst

   1 .. Thun documentation master file, created by
   2    sphinx-quickstart on Sun Apr 22 15:19:55 2018.
   3    You can adapt this file completely to your liking, but it should at least
   4    contain the root `toctree` directive.
   5
   6 Thun |release| Documentation
   7 ============================
   8
   9 Thun is dialect of Joy written in Python.
  10
  11 `Joy`_ is a programming language created by Manfred von Thun that is easy to
  12 use and understand and has many other nice properties.  This Python
  13 package implements an interpreter for a dialect of Joy that attempts to
  14 stay very close to the spirit of Joy but does not precisely match the
  15 behaviour of the original version(s) written in C.  The main difference
  16 between Thun and the originals, other than being written in Python, is
  17 that it works by the "Continuation-Passing Style".
  18
  19 Joy is:
  20
  21 * `Purely Functional <https://en.wikipedia.org/wiki/Purely_functional_programming>`__
  22 * `Stack-based <https://en.wikipedia.org/wiki/Stack-oriented_programming_language>`__
  23 * `Concatinative`_ ( See also `concatenative.org <http://www.concatenative.org/wiki/view/Concatenative%20language>`__)
  24 * :doc:`Categorical <notebooks/Categorical>`
  25
  26 I hope that this package is useful in the sense that it provides an
  27 additional joy interpreter (the binary in the archive from La Trobe seems
  28 to run just fine on my modern Linux machine!)  But I also hope that you
  29 can read and understand the Python code and play with the implementation
  30 itself.
  31
  32 .. _Joy: https://en.wikipedia.org/wiki/Joy_(programming_language)
  33
  34 .. _Concatinative: https://en.wikipedia.org/wiki/Concatenative_programming_language
  35
  36
  37 Example Code
  38 --------------------------------------------------
  39
  40 Here is an example of Joy code::
  41
  42     [[[abs]ii <=][[<>][pop !-]||]&&][[!-][[++]][[--]]ifte dip][[pop !-][--][++]ifte]ifte
  43
  44 It might seem unreadable but with a little familiarity it becomes just as
  45 legible as any other notation.  Some layout helps::
  46
  47     [   [[abs] ii <=]
  48         [
  49             [<>] [pop !-] ||
  50         ] &&
  51     ]
  52     [[    !-] [[++]] [[--]] ifte dip]
  53     [[pop !-]  [--]   [++]  ifte    ]
  54     ifte
  55
  56 This function accepts two integers on the stack and increments or
  57 decrements one of them such that the new pair of numbers is the next
  58 coordinate pair in a square spiral (like the kind used to construct an
  59 `Ulam Spiral`_).  For more information see :doc:`notebooks/Square_Spiral`
  60
  61 .. _Ulam Spiral: https://en.wikipedia.org/wiki/Ulam_spiral
  62
  63
  64 Quick Start
  65 --------------------------------------------------
  66
  67 Install from `PyPI`_ in the usual way::
  68
  69     $ pip install Thun
  70
  71 To start the REPL::
  72
  73     $ python -m joy
  74
  75 Continue with :doc:`the introduction <notebooks/Intro>`.
  76
  77 .. _PyPI: https://pypi.org/project/Thun/
  78
  79
  80 Project Hosted on `OSDN`_
  81 -------------------------
  82
  83 * `Source Repository`_ (`mirror`_)
  84 * `Bug tracker`_ (`old tracker`_)
  85 * `Forums`_
  86 * `Mailing list`_
  87
  88 .. _Bug tracker: https://todo.sr.ht/~sforman/thun-der
  89 .. _old tracker: https://osdn.net/projects/joypy/ticket/
  90 .. _Forums: https://osdn.net/projects/joypy/forums/
  91 .. _Mailing list: https://osdn.net/projects/joypy/lists/
  92 .. _OSDN: https://osdn.net/projects/joypy/
  93 .. _Source Repository: https://osdn.net/projects/joypy/scm/git/Thun/
  94 .. _mirror: https://github.com/calroc/Thun
  95
  96
  97 Information on the Joy language
  98 -------------------------------
  99
 100 See `the Wikipedia article`_ and `Kevin Albrecht's mirror of Manfred von Thun's original website for the Joy Programming Language`_ for more information on the Joy language.
 101
 102 The best source (no pun intended) for learning about Joy is the
 103 information made available at the website of La Trobe University (see the
 104 mirror link above) which contains source code for the
 105 original C interpreter, Joy language source code for various functions,
 106 and a great deal of fascinating material mostly written by Von Thun on
 107 Joy and its deeper facets as well as how to program in it and several
 108 interesting aspects.  It's quite a treasure trove.
 109
 110 .. _the Wikipedia article: https://en.wikipedia.org/wiki/Joy_(programming_language)
 111
 112 .. _Kevin Albrecht's mirror of Manfred von Thun's original website for the Joy Programming Language: http://www.kevinalbrecht.com/code/joy-mirror/index.html
 113
 114
 115 Documentation on Thun Dialect
 116 -----------------------------
 117
 118 The following is specific information for this dialect of Joy.
 119
 120 .. toctree::
 121    :maxdepth: 2
 122
 123    notebooks/Intro
 124    joy
 125    stack
 126    parser
 127    pretty
 128    library
 129    lib
 130    types
 131    notebooks/index
 132
 133
 134
 135 Indices and tables
 136 ==================
 137
 138 * :ref:`genindex`
 139 * :ref:`modindex`
 140 * :ref:`search`