More documentation.

asciiWriter/marks.py

@@ -1,12 +1,18 @@
 from random import choice
+from string import ascii_letters
 
-def random (marks=['']):
+def random (marks=ascii_letters):
+  """Random mark from provided marks."""
   def func ():
     return choice(marks)
 
   return func
 
 def sentence (text):
+  """Deprecated. Use text."""
+
+def text (text):
+  """Loops through provided text."""
   chars = list(text)
   def f():
     char = chars.pop(0)
@@ -15,10 +21,12 @@ def sentence (text):
   return f
  
 def single (char):
+  """Mark with a single character."""
   def f():
     return char
 
   return f
 
 def space (space=' '):
+  """Convenience function to mark with spaces."""
   return single(space)

asciiWriter/patterns.py

@@ -1,7 +1,7 @@
 import math
 
-# # Linear
 def diagonal():
+  """Draw a diagnal line from top left to bottom right"""
   def f (x, y, width, height, mark, blank):
     if x == math.floor((y / float(height)) * width):
       return mark()
@@ -12,6 +12,7 @@ def diagonal():
 
 # Cross
 def cross ():
+  """Draw two diagonals"""
   def f (x, y, width, height, mark, blank):
     pos = math.floor((y / float(height)) * width)
 
@@ -22,17 +23,20 @@ def cross ():
   return f
 
 def horizontal (position):
+  """Draw horizontal line at given Y position."""
   def f (x, y, width, height, mark, blank):
     return mark() if position == y else blank()
   return f
 
 def vertical (position):
+  """Draw a vertical line at given X position."""
   def f (x, y, width, height, mark, blank):
     return mark() if position == x else blank()
   return f
 
 # Sinus
 def sinus_vertical (period=0.2, amplitude=0.5, offset_t=0, offset=0):
+  """Draw a sinus shape vertically"""
   period = (period / (math.pi * 2))
   
   def f (x, y, width, height, mark, blank):
@@ -42,6 +46,7 @@ def sinus_vertical (period=0.2, amplitude=0.5, offset_t=0, offset=0):
   return f
 
 def sinus_horizontal (period=0.2, amplitude=0.5, offset_t=0, offset=0):
+  """Draw a sinus shape horizontally"""
   period = (period / (math.pi * 2))
   def f (x, y, width, height, mark, blank):
     middle = (height - 1) * .5
@@ -51,7 +56,12 @@ def sinus_horizontal (period=0.2, amplitude=0.5, offset_t=0, offset=0):
   return f
 
 def image (path, threshold=128):
-  from PIL import Image
+  """Put marks based on a mask. Requires Pillow"""
+  try:
+    from PIL import Image
+  except ImportError:
+    print('The image patter requires pillow to be installed.')
+    exit()
 
   im = Image.open(path).convert('L')
   image_width, image_height = im.size

asciiWriter/text.py

@@ -3,7 +3,7 @@ from .wrap_single_line import wrap_single_line
 from .utils import translate, merge
 
 def make_column(text, line_width=50, height=200, use_hyphenator=None, line_offset=0):
-    
+  """Generate a layer width a text column."""    
   lines = []
   remaining = text
 
@@ -31,8 +31,8 @@ def make_column(text, line_width=50, height=200, use_hyphenator=None, line_offse
   return lines, remaining
 
 def make_multi_column(text, height=200, column_width=40, column_count=2, column_gap=5, use_hyphenator=None, space_char=None):
-  # todo: vertical offset?
-  
+  """Generate a layer with multiple text columns."""
+
   remaining = text 
   i = 0
 

asciiWriter/utils.py

@@ -1,6 +1,7 @@
 from sys import stdout
 
 def rotate(layer):
+  """ Rotates a layer 90 degrees """
   new_width = len(layer)
   new_height = len(layer[0])
   rotated = [['' for x in range(new_width)] for l in range(new_height)]
@@ -12,6 +13,12 @@ def rotate(layer):
   return rotated
 
 def merge(width, height, space_char, layers):
+  """Merges given layers in a new grid with given width and height. 
+  
+  Merges layers into a new grid with the given width and height.
+  For each cell the last value is taken, unless it is empty.
+  Cells with the provided space char are considered empty.
+  """
   output = [[space_char for x in range(width)] for y in range(height)]
 
   for layer in layers:
@@ -22,40 +29,54 @@ def merge(width, height, space_char, layers):
 
   return output
 
-# Make a multidimensional array
-# with the given dimensions
 def make_lines (width, height, fill_char = ''):
+  """Deprecated. Use make_layer instead."""
+  return make_layer(width, height, fill_char)
+
+def make_layer (width, height, fill_char = ''):
+  """Construct a layer with given width and height.
+     
+     Construct a layer with given width and height.
+     If fillchar is provided it is used to fill the grid.
+  """
   return [[ fill_char for _ in range(width) ] for __ in range(height)]
 
-def visit (lines, callback, mark, blank):
-  height = len(lines)
-  width = len(lines[0])
+def visit (layer, pattern, mark, blank):
+  """Apply pattern on the provided layer. Row by row."""
+  height = len(layer)
+  width = len(layer[0])
 
   for y in range(height):
     for x in range(width):
-      lines[y][x] = callback(x, y, width, height, mark, blank)
+      layer[y][x] = pattern(x, y, width, height, mark, blank)
 
-  return lines
+  return layer
 
-def visit_horizontal (lines, callback, mark, blank):
-  height = len(lines)
-  width = len(lines[0])
+def visit_horizontal (layer, pattern, mark, blank):
+  """Apply pattern on the provided layer. Column by column."""
+  height = len(layer)
+  width = len(layer[0])
 
   for x in range(width):
     for y in range(height):
-      lines[y][x] = callback(x, y, width, height, mark, blank)
+      layer[y][x] = pattern(x, y, width, height, mark, blank)
 
-  return lines
+  return layer
 
 def print_lines (lines):
-  for line in lines:
-    stdout.write('{}\n'.format(''.join(line)))
+  """Deprecated. Use print_layer instead."""
+  print_layer(lines, out=stdout)
+  
+def print_layer(layer, out=stdout):
+  """Print / write layer to provided output."""
+  for line in layer:
+    out.write('{}\n'.format(''.join(line)))
 
-def translate(shape, x=0, y=0):
-  ## TODO implement a negative translation?
+def translate(layer, x=0, y=0, fill_char=None):
+  """Translate layer by provided x and y lengths."""
   translated = [[] for _ in range(y)]
 
-  for line in shape:
-    translated.append([None for _ in range(x)] + line)
+  for line in layer:
+    translated.append([fill_char for _ in range(x)] + line)
 
   return translated