Minor cleanup.

vlist.py

@@ -3,13 +3,15 @@ An exploration of Phil Bagwell's VList.
 
 A VList is modeled as a 5-tuple:
     base: VList
-    offset: int (indexing base VList data)
-    size: int
+    offset: int, indexing (from 0) the base VList data list.
+    size: int, length of the data list.
     last_used: to make a mutable int it's an int in a list
                It's a count here rather than an offset!
-    data: a list of length length
+               That is, it starts from 1, rather than 0.
+    data: a list of length size.
 
-a Pointer to a VList is a pair of (VList and offset).
+A pointer to a VList is a two-tuple of (VList, offset) where
+the offset is an index into the VList's data list.
 
 '''
 
@@ -18,34 +20,36 @@ def cons(thing, vlist_ptr):
     if not vlist_ptr:
         return ((), 0, 1, [1], [thing]), 0
 
-    (base, offset, size, last_used_list, data), pointer_offset = vlist_ptr
+    (base, _offset, size, last_used_list, data), pointer_offset = vlist_ptr
     [last_used] = last_used_list
 
     '''
-
-    During the consing of (9) the pointer offset
-    is compared with the last used offset, LastUsed. If it is the same and less than
-    the block size then it is simply incremented, the new entry made and LastUsed
+    During the consing of (9) the pointer offset is compared with the
+    last used offset, LastUsed. If it is the same and less than the block
+    size then it is simply incremented, the new entry made and LastUsed
     updated.
-
     '''
+
     if pointer_offset == last_used - 1 and last_used < size:
         pointer_offset += 1
         data[pointer_offset] = thing
         last_used_list[0] = last_used + 1
         return vlist_ptr[0], pointer_offset
-    '''
-
-    If on the other-hand the pointer offset is less than the LastUsed a cons is being applied
-    to the tail of a longer list, as is the case with the (9). In this case a new list block
-    must be allocated and its Base-Offset pointer set to the tail contained in the original
-    list. The offset part being set to the point in tail that must be extended. The new
-    entry can now be made and additional elements added.
 
     '''
+    If on the other-hand the pointer offset is less than the LastUsed a
+    cons is being applied to the tail of a longer list, as is the case
+    with the (9). In this case a new list block must be allocated and its
+    Base-Offset pointer set to the tail contained in the original list.
+    The offset part being set to the point in tail that must be extended.
+    The new entry can now be made and additional elements added.
+    '''
+
     # Is this where we increase the size x 2?
-    size <<= 1 ; l = [None] * size ; l[0] = thing
-    return (vlist_ptr[0], pointer_offset, size, [1], l), 0
+    size <<= 1
+    data = [None] * size
+    data[0] = thing
+    return (vlist_ptr[0], pointer_offset, size, [1], data), 0
 
 
 def head(vlist_ptr):
@@ -78,11 +82,10 @@ def pick(n, vlist_ptr):
         raise ValueError("Empty list!")
 
     '''
-
-    Consider starting with a list pointer in Fig 1 then to find the nth element subtract
-    n from the pointer offset. If the result is positive then the element is in the first
-    block of the list at the calculated offset from the base. If the result is negative then...
-
+    Consider starting with a list pointer in Fig 1 then to find the nth
+    element subtract n from the pointer offset. If the result is positive
+    then the element is in the first block of the list at the calculated
+    offset from the base. If the result is negative then...
     '''
 
     vlist, pointer_offset = vlist_ptr
@@ -91,13 +94,12 @@ def pick(n, vlist_ptr):
         return vlist[-1][q]
 
     '''
-
-    ...move to the next block using the Base-Offset pointer. Add the Previous pointer
-    offset to the negative offset. While this remains negative keep moving onto the next
-    block. When it finally becomes positive the position of the required element has
-    been found
-
+    ...move to the next block using the Base-Offset pointer. Add the
+    Previous pointer offset to the negative offset. While this remains
+    negative keep moving onto the next block. When it finally becomes
+    positive the position of the required element has been found
     '''
+
     while True:
         assert q < 0
         if not vlist: