docs/README.md

   1 # Some Jupyter Notebooks and other material.
   2
   3 All of the notebooks are also available as HTML and Markdown files (generated using nbconvert) so you can view them without running Jupyter.
   4
   5 In order to run the [Jupyter Notebooks](https://jupyter.org/index.html) you need Jupyter (obviously) and you should install `Joypy`.  Here's an example using `virtualenv` from the project directory:
   6
   7     virtualenv --system-site-packages venv
   8     source ./venv/bin/activate
   9     pip install notebook
  10     python ./setup.py install
  11
  12 Once that's done you should be able to start Jupyter Notebook server with, e.g.:
  13
  14     python -m notebook --ip=0.0.0.0
  15
  16 This starts it using the `virtualenv` version of Python so `joy` will be available.  Navigate to the `joypy/docs` directory and the notebooks should be able to import the `notebook_preamble.py` file.
  17
  18 I find I have to include `--ip=0.0.0.0` to workaround a bug where it tries to bind to an IPv6 address, YMMV.
  19
  20 ## Table of Contents
  21
  22 - 1. Basic Use of Joy in a Notebook
  23 - 2. Library Examples - Short examples of each word in the dictionary.  Various formats.
  24 - 3. Developing a Program - Working with the first problem from Project Euler, "Find the sum of all the multiples of 3 or 5 below 1000", several forms of the program are derived.
  25 - 4. Replacing Functions in the Dictionary - Shows the basics of defining new "primitive" functions in Python or as definitions and adding them to the dictionary.
  26 - Factorial Function and Paramorphisms - A basic pattern of recursive control-flow.
  27 - Generator Programs - Using the x combinator to make generator programs which can be used to create unbounded streams of values.
  28 - Hylo-, Ana-, Cata-morphisms - Some basic patterns of recursive control-flow structures.
  29 - Quadratic - Not-so-annoying Quadratic Formula.
  30 - Trees - Ordered Binary Trees in Joy and more recursion.
  31 - Zipper - A preliminary examination of the idea of data-structure "zippers" for traversing datastructures.
  32 - notebook_preamble.py - Imported into notebooks to simplify the preamble code.
  33 - pe1.py pe1.txt - Set up and execute a Joy program for the first problem from Project Euler. The pe1.txt file is the trace.  It's 2.8M uncompressed.  Compressed with gzip it becomes just 0.12M.
  34 - repl.py - Run this script to start a REPL.  Useful for e.g. running Joy code in a debugger.
  35
  36 ## Notes
  37
  38 One of the things that interests me about Joy is how programming becomes
  39 less about writing code and more about sound reasoning about simple
  40 (almost geometric) programs.  Many of the notebooks in this collection
  41 consist of several pages of discussion to arrive at a few lines of Joy
  42 definitions.  I think this is a good thing.  This is "literate
  43 programming".  The "programs" resemble mathematical proofs.  You aren't
  44 implementing so much as deriving.  The structure of Joy seems to force
  45 you to think clearly about the task in a way that is reliable but
  46 extremely flexible.  It feels like a puzzle game, and the puzzles are
  47 often simple, and the solutions build on each other.