Improved documentation

.travis.yml

@@ -1,21 +1,23 @@
 dist: xenial
 language: python
 python:
-- '2.7'
-- '3.5'
-- '3.6'
-- '3.7'
-- 3.7-dev
-- 3.8-dev
-- nightly
+  - '2.7'
+  - '3.5'
+  - '3.6'
+  - '3.7'
+  - 3.7-dev
+  - 3.8-dev
+  - nightly
 install:
-- pip install -r requirements-dev.txt
-- pip install .
+  - pip install -r requirements-dev.txt
+  - pip install -r docs/requirements.txt
+  - pip install .
 script:
-- pylint tagged_union --py3k
-- pytest --cov=tagged_union
+  - pylint tagged_union --py3k
+  - pytest --cov=tagged_union
+  - make -C docs/ html
 after_success:
-- coveralls
+  - coveralls
 deploy:
   provider: pypi
   user: Carotti

docs/conf.py

@@ -9,10 +9,9 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
 
 
 # -- Project information -----------------------------------------------------
@@ -22,7 +21,7 @@
 author = 'Thomas Carotti'
 
 # The full version, including alpha/beta/rc tags
-release = '0.0.1'
+release = '0.0.2'
 
 
 # -- General configuration ---------------------------------------------------
@@ -31,7 +30,8 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.napoleon'
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -42,6 +42,8 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+# Set the master document to index.rst
+master_doc = 'index'
 
 # -- Options for HTML output -------------------------------------------------
 

docs/examples.rst

@@ -0,0 +1,14 @@
+Examples
+========
+
+Successor Definition of Natural Numbers
+---------------------------------------
+
+.. literalinclude:: ../examples/nat.py
+  :language: python
+
+Sorted, "Immutable" Binary Tree
+-------------------------------
+
+.. literalinclude:: ../examples/btree.py
+    :language: python

docs/index.rst

@@ -1,16 +1,14 @@
-.. Tagged Union documentation master file, created by
-   sphinx-quickstart on Mon Jun 24 17:58:44 2019.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to Tagged Union's documentation!
-========================================
+Python Tagged Union
+===================
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+    :maxdepth: 2
+    :caption: Contents:
 
+    examples
 
+.. automodule:: tagged_union
+    :members:
 
 Indices and tables
 ==================

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx
+sphinxcontrib-napoleon

examples/btree.py

@@ -0,0 +1,37 @@
+from tagged_union import Unit, Self, tagged_union, match
+
+@tagged_union
+class BTree(object):
+    branch = (Self, Self, object)
+    leaf = Unit
+
+    def add(self, data):
+        return match(self, {
+            BTree.leaf: lambda: BTree.branch(BTree.leaf(), BTree.leaf(), data),
+            BTree.branch: lambda l, r, d:
+                BTree.branch(l.add(data), r, d) if data <= d \
+                    else BTree.branch(l, r.add(data), d)
+        })
+
+    def __repr__(self):
+        return match(self, {
+            BTree.leaf: lambda: "",
+            BTree.branch: lambda l, r, d:
+                repr(l) + "/" + repr(d) + "\\" + repr(r),
+        })
+
+empty_btree = BTree.leaf()
+
+print(empty_btree == BTree.leaf())
+
+a = empty_btree.add(5)
+
+print(a)
+
+b = a.add(6)
+
+print(b)
+
+c = b.add(4)
+
+print(c)

requirements-dev.txt

@@ -2,5 +2,3 @@ coveralls
 pylint
 pytest
 pytest-cov
-sphinx
-sphinxcontrib-napoleon

tagged_union/__init__.py

@@ -1,4 +1,4 @@
-"""Tagged Unions
+"""Python implementation of tagged unions.
 
 Python tagged unions (aka sum types, algebraic data types, etc.) are a common
 tool in functional and functional style programming. This module provides a
@@ -13,20 +13,54 @@ class attributes, equal to a type or tuple of types representing how that union
 tagged union class, allowing common implementations inside this class.
 
 Example:
+    It is worth noting that python imports ignores identifiers which start with
+    `_`, so if you wish to use the `_` identifier as a wildcard for matching,
+    it must be imported explicitly::
+
+        from tagged_union import _
+        from tagged_union import *
+
     The following example creates a tagged union which has two members, `Foo`
     and `Bar`. `Foo` accepts no arguments as its constructor and `Bar` accepts
     an instance of MyTaggedUnion (either another `Bar` or a `Foo`)::
 
         @tagged_union
-        class MyU:
+        class MyU(object):
             Foo = Unit
             Bar = Self
 
         test = MyU.Bar(MyU.Bar(MyU.Bar(MyU.Foo())))
+        print(test)
+
+    It is then possible to use the match function against this new object. In
+    this case, the `count` function counts how many MyU.Bar constructors appear
+    in the object::
+
+        def count(test):
+            return match(test, {
+                MyU.Foo: lambda: 0,
+                MyU.Bar: lambda x: 1 + count(x),
+            })
+
+        print(count(test))
+
+    In its naive form, the match function can behave like a switch statement,
+    if not used on a tagged union type. This also still supports `_` for
+    wildcarding matches::
+
+        def name_to_id(name):
+            return match(name, {
+                "Tom": lambda: 11,
+                "Sarah": lambda: 12,
+                _: lambda: -1,
+            })
+
+        print(name_to_id("Tom"))
+        print(name_to_id("Michael"))
 
 Attributes:
     Self (type): For defining recursive tagged unions. `Self` is replaced with
-    the type of the tagged union class itself.
+        the type of the tagged union class itself.
 
     Unit (type): Use as a type for tagged union members who accept no arguments
         in their constructors. Also used internally as a sentinel to check that
@@ -150,7 +184,7 @@ def match(union, branches):
 
     Allows matching of instances of tagged union members against their type.
     Can also just be used as a switch-like statement if used with other objects
-    such as `int`s. Uses the tagged union member's constructor arguments as the
+    such as `int`. Uses the tagged union member's constructor arguments as the
     arguments to the matching branch's function.
 
     Args: