change 'seed' to 'game_id', write docs'

1 files changed, 39 insertions, 20 deletions

diff --git a/oo.py b/oo.py
index 1b0d4b4..158e404 100644
--- a/oo.py
+++ b/oo.py
@@ -11,12 +11,12 @@ class ooPuzzle:
          pieces : dictionary mapping (x,y) to range(6)
         orients : dictionary mapping (x,y) to range(4)
     """
-    def __init__(self, X, Y, seed=None, inverted=False, toroidal=False):
+    def __init__(self, X, Y, game_id=None, inverted=False, toroidal=False):
         """Create a new ooPuzzle instance.
 
         Arguments.
                  X,Y : horizontal and vertical size of the puzzle
-                seed : passed to ooPuzzle.set_pieces_from_seed
+             game_id : passed to ooPuzzle.set_pieces_from_game_id
             inverted : bool for swapping to "dark mode"
             toroidal : bool for looping around the end of the puzzle
 
@@ -27,7 +27,7 @@ class ooPuzzle:
         self.toroidal = toroidal
         self.pieces  = {}
         self.orients = {}
-        self.set_pieces_from_seed(seed)
+        self.set_pieces_from_game_id(game_id)
 
     EDGES_TO_PIECE_ORIENT = { (0, 0, 0, 0) : (0, 0),
 
@@ -78,6 +78,23 @@ class ooPuzzle:
 
     def set_pieces_from_edges(self, horiz_edges, vert_edges):
         """Convert edge dictionaries into a puzzle state.
+
+        Adjacent edges in a solution must be
+        either both filled or both unfilled,
+        and so a bit of data is assigned to each pair.
+        
+        vert_edges is the dictionary for vertical pairs
+          key: (x, row)
+            x: the usual x-coordinate of the piece
+          row: the y-coordinate or y+1, depending on whether
+               you want the pair above or below the piece
+             : row == 0 and row == self.Y are border edges
+               so it's good to think of row as 1-indexed
+        
+        horiz_edges is the dictionary for horizontal pairs
+          key: (col, y)
+          col: the x-coord or x+1, same as row but left or right
+            y: the usual y-coord
         """
         for x in range(self.X):
             for y in range(self.Y):
@@ -89,16 +106,18 @@ class ooPuzzle:
 
                 piece, orient = \
                     self.EDGES_TO_PIECE_ORIENT[left, up, right, down]
-                self.pieces[x, y]  = piece
+                self.pieces [x, y] = piece
                 self.orients[x, y] = orient
 
-    def set_pieces_from_seed(self, seed=None):
-        """Convert seed value into a solution puzzle state.
+        #TODO: properly account for the borders if toroidal
+
+    def set_pieces_from_game_id(self, game_id=None):
+        """Convert game_id value into a solution puzzle state.
 
-        seed is an integer
+        game_id is an integer
             if     toroidal: in range(2**( 2*X*Y ))
             if not toroidal: in range(2**( (X-1)*Y + X*(Y-1) ))
-        if None, then a random seed is generated
+        if None, then a random game_id is generated
         """
 
         # compute:
@@ -111,14 +130,13 @@ class ooPuzzle:
         n_horiz =  n_col * self.Y
         n_vert  = self.X * n_row
 
-        # generate and record seed
+        # generate and record game_id
 
-        if seed == None:
-            maxint = 2**(n_horiz + n_vert - 1)
-            seed = random.randint(0, maxint)
-        self.seed = seed
+        if game_id == None:
+            game_id = random.randrange(0, 2**(n_horiz + n_vert))
+        self.game_id = game_id
 
-        # prepare to record edges
+        # prepare to record edges for self.set_pieces_from_edges
 
         vert_edges  = {}
         horiz_edges = {}
@@ -134,16 +152,16 @@ class ooPuzzle:
             horiz_edges[     0, y] = 0
             horiz_edges[self.X, y] = 0
 
-        # set the edges determined by seed
+        # set the edges determined by game_id
 
         for i in range(n_vert):
             row, x = divmod(i, self.X)
-            seed, bit = divmod(seed, 2)
+            game_id, bit = divmod(game_id, 2)
             vert_edges[x, row+1] = bit
 
         for i in range(n_horiz):
             col, y = divmod(i, self.Y)
-            seed, bit = divmod(seed, 2)
+            game_id, bit = divmod(game_id, 2)
             horiz_edges[col+1, y] = bit
 
         # turn edges into pieces
@@ -183,11 +201,12 @@ class ooPlay:
         self.display()
 
     PIECE_ORIENT_TO_STRING = \
-        ["╸╵╺╷",
+        ["    ",
+         "╸╵╺╷",
          "┙┕┍┑",
          "━│━│",
-         "┝┯┥┷"]
-
+         "┝┯┥┷",
+         "┿┿┿┿"]
 
     def display(self):
         """Display the state of the board, refresh screen."""