changeset 54:9b17819287ce

Added comments.
author Janus Dam Nielsen <janus.nielsen@alexandra.dk>
date Tue, 26 May 2009 17:10:21 +0200
parents 709a931db194
children de686d4704ee
files pysmcl/range_analysis.py
diffstat 1 files changed, 56 insertions(+), 3 deletions(-) [+]
line wrap: on
line diff
--- a/pysmcl/range_analysis.py	Tue May 26 16:47:39 2009 +0200
+++ b/pysmcl/range_analysis.py	Tue May 26 17:10:21 2009 +0200
@@ -1,29 +1,59 @@
+#
+#
+#
+#
 
+""" This module implements a range analysis of expressions in the 
+core PySMCL language.
+
+The lattice is the power set lattice over all variables and their range in a given 
+function. A range is represented as a tuple of two numbers or the bottom element.
+"""
+
+# Import system packages.
 import ast
 
+# Import PySMCL packages.
 from pysmcl import flow
 
+# Switch to True for debug output printed to std. out.
 debug = False
 
 class Bottom(object):
+    """The element used to represent intervals that are not between 0 and p.
     
+    e.g. for the expression x = 2-5 yields the range for x (Bottom(), Bottom())
+    """
     def __eq__(self, other):
         if other is not None:
             return isinstance(other, Bottom)
         return False
 
 class RangeAnalysis(object):
+    """The class which defines the range analysis.
 
-    result = None
+    Call the apply method to perform the range analysis on a FunctionDef object.
+    """
+
+    # The key used in the flow framework for our analysis
     key = "range"
 
     def __init__(self, prime):
+        """prime (integer) defines the field of computation, Zp."""
         self.prime = prime
 
     def apply(self, function):
+        """Perform the analysis
+
+        function (FunctioDef)
+        """
         flow.analyze(function, self.join, self.combine, self.key, lambda : {})
 
     def join(self, in_nodes):
+        """The join function in the monotome framework.
+        
+        in_nodes (Set) a set of predecessor nodes.
+        """
         if debug:
             print "Join"
         env = {}
@@ -34,13 +64,19 @@
         return env
 
     def combine(self, node, env):
+        """The least upper bound of the node and the environment.
+
+        node (ast.Node)
+        end (dict) A dictionary with variables and their current range.
+        """
         if debug:
             print "========= Combining ==========="
             print "Node, env", node, env
 
         class Visitor(ast.NodeVisitor):
-
+            """Visitor for Python statements."""
             def __init__(self, prime):
+                """prime (integer) defines the field of computation, Zp."""
                 self.prime = prime
 
             def visit_Assign(self, node):
@@ -67,12 +103,23 @@
 
 
 def range(prime, node, env):
+    """range performs the computation of range of the given node.
+
+    node (ast.Node)
+    env (dict) An environment of variables and their range.
+    """
     rangeVisitor = RangeVisitor(prime, env)
     return rangeVisitor.visit(node)        
 
 class RangeVisitor(ast.NodeVisitor):
+    """RangeVisitor is the visitor which actually implements the 
+    range computation."""
 
     def __init__(self, prime, env):
+        """
+        prime (integer) defines the field of computation, Zp.
+        env (dict) An environment of variables and their range.
+        """
         self.prime = prime
         self.env = env
 
@@ -131,7 +178,11 @@
         return (0, self.prime)
 
 class TargetVisitor(ast.NodeVisitor):
-    """The following expression can appear in assignment context """                         
+    """TargetVisitor update range of target of an assignment in the given environment.
+
+    The following expression can appear in assignment contexts:
+    Attribute, Subscript, Name, List, Tuple.
+    """
 
     def __init__(self, env, range):
         self.env = env
@@ -156,6 +207,7 @@
         pass
 
 def combine_env(env1, env2):
+    """Combine the two environments env1 and env2."""
     env = {}
     common_keys = set(env1.keys()) & set(env2.keys())
     env1_keys = set(env1.keys()) - set(env2.keys())
@@ -169,6 +221,7 @@
     return env
 
 def combine_range((l1, h1), (l2, h2)):
+    """Combine the two ranges."""
     r = (Buttom(),Buttom())
     if l1 < l2:
         r[0] = l1