owl-basic 0.6.0__py3-none-any.whl

owl_basic/flow/basic_block_orderer.py

@@ -0,0 +1,29 @@
+'''
+Created on 9 Feb 2010
+
+@author: rjs
+'''
+import logging
+logger = logging.getLogger('flow.basic_block_orderer')
+
+from .traversal import approximateTopologicalOrder
+
+def orderBasicBlocks(basic_blocks, options):
+    '''
+    :param basic_blocks: A dictionary of entry blocks - BasicBlock instances through which control
+                         flow enters the graph of each program, function or procedure. The keys are
+                         the entry point names.
+    :param options: Command line options
+    :returns: A dictionary of lists of basic blocks in approximate topological order. Keys are entry_point names
+    '''
+    ordered_blocks = {}
+    for name, basic_block in basic_blocks.items():
+        logger.debug(name)
+        order = approximateTopologicalOrder(basic_block)
+        print("order = ", order)
+        for i, block in enumerate(order):
+            block.topological_order = i
+        ordered_blocks[name] = order
+    return ordered_blocks
+
+        

owl_basic/flow/connectors.py

@@ -0,0 +1,19 @@
+'''
+Functions for manipulating the control flow graph
+'''
+
+from owl_basic.ast_utils import findFollowingStatement
+
+def connectToFollowing(statement):
+    following = findFollowingStatement(statement)
+    if following is not None:
+        connect(statement, following)
+
+def connect(from_statement, to_statement):
+    from_statement.addOutEdge(to_statement)
+    to_statement.addInEdge(from_statement)
+
+def connectLoop(from_statement, to_statement):
+    from_statement.addLoopBackEdge(to_statement)
+    to_statement.addLoopFromEdge(from_statement)
+    

owl_basic/flow/convert_sub_visitor.py

@@ -0,0 +1,28 @@
+from owl_basic.visitor import Visitor
+from owl_basic.ast_utils import replaceStatement
+from owl_basic.syntax.ast import LiteralInteger, CallProcedure, ReturnFromProcedure
+from owl_basic import errors
+
+class ConvertSubVisitor(Visitor):
+    """
+    Replaces RETURN with ENDPROC
+    """
+    
+    def __init__(self):
+        pass
+            
+    def visitAstNode(self, node):
+        node.forEachChild(self.visit)
+        
+    def visitGosub(self, gosub):
+        if isinstance(gosub.targetLogicalLine, LiteralInteger):
+            # Convert to a procedure call
+            proc = CallProcedure(name="PROCSub" + str(gosub.targetLogicalLine.value))
+            replaceStatement(gosub, proc)           
+        else:
+            errors.fatalError("Cannot compile computed GOSUB target at line %s" % gosub.lineNum)        
+        
+    def visitReturn(self, ret):
+        # Convert each RETURN to an ENDPROC by changing the class
+        ret.__class__ = ReturnFromProcedure
+        

owl_basic/flow/entry_point_locator.py

@@ -0,0 +1,55 @@
+import sys
+import logging
+
+from owl_basic.syntax import ast
+from owl_basic import ast_utils
+from owl_basic import errors
+from . import flow_analysis
+
+from .entry_point_visitor import EntryPointVisitor
+
+
+def locateEntryPoints(parse_tree, line_mapper, options):
+    '''
+    Locate all the program, procedure, function and subroutine entry points in the program
+    represented by parse_tree.
+    :param parse_tree: The root AstNode of an abstract syntax tree representing the program.
+    :param line_mapper: A LineMapper for the program.
+    :param options: Command line options.
+    :returns: A dictionary of entry point names to entry point AstStatement nodes.  The name
+              of the program entry point, if there is one, will be '__owl__main'
+    '''
+    logging.debug("locateEntryPoints")    
+    epv = EntryPointVisitor(line_mapper)
+    parse_tree.accept(epv)
+    first_statement = line_mapper.firstStatement()
+    epv.mainEntryPoint(first_statement)
+    entry_points = epv.entryPoints
+    # Tag each statement with its predecessor entry point
+    logging.debug("Tagging statements with entry point\n")
+    for entry_point in entry_points.values():
+        flow_analysis.tagSuccessors(entry_point, line_mapper)
+        
+    guardExecutableDefinitions(entry_points)
+    return entry_points
+
+def guardExecutableDefinitions(entry_points):
+    logging.debug("Checking for direct execution of function or procedure bodies...")
+    
+    for entry_point in entry_points.values():
+        if isinstance(entry_point, ast.DefinitionStatement):
+            if len(entry_point.inEdges) != 0:
+                
+                reachable_predecessors = (len(predecessor.entryPoints) > 0 for predecessor in entry_point.inEdges)
+                if any(reachable_predecessors):
+                    errors.warning("Execution of procedure/function at line %s" % entry_point.lineNum)
+                    # TODO: Could use ERROR statement here
+                    # TODO: Could also have an option to allow procedures to be directly executable
+                    # which may involve inserting a call to the procedure at this point ... probably
+                    # more appropriate for GOSUBroutines.
+                    raise_stmt = ast.Raise(type="ExecutedDefinitionException")
+                    raise_stmt.lineNum = entry_point.lineNum
+                    ast_utils.insertStatementBefore(entry_point, raise_stmt)
+                    raise_stmt.clearOutEdges()
+                    entry_point.clearInEdges()
+    return entry_point, entry_points

owl_basic/flow/entry_point_visitor.py

@@ -0,0 +1,48 @@
+from owl_basic.visitor import Visitor
+from owl_basic.ast_utils import *
+from owl_basic import errors
+
+class EntryPointVisitor(Visitor):
+    """
+    This enumerates all of the entry-points in the supplied AST
+    """
+    
+    def __init__(self, line_mapper):
+        # TODO: This should locate its own root, finding it on demand
+        self.line_mapper = line_mapper
+        self.__entry_points = {}
+    
+    entryPoints = property(lambda self: self.__entry_points)
+                
+    def mainEntryPoint(self, statement):
+        '''
+        Set the main() entrypoint of the program (i.e. the first line)
+        '''
+        if not hasattr(statement, "entryPoint"):
+            statement.entryPoint = "__owl__main"
+        self.__entry_points['__owl__main'] = statement
+            
+    def visitAstNode(self, node):
+        "Visit all children in order"
+        node.forEachChild(self.visit)
+        
+    def visitDefineProcedure(self, defproc):
+        self.__entry_points[defproc.name] = defproc
+        defproc.entryPoint = "public"
+        
+    def visitDefineFunction(self, deffn):
+        self.__entry_points[deffn.name] = deffn
+        deffn.entryPoint = "public"
+        
+    def visitGosub(self, gosub):
+        gosub_target = self.line_mapper.statementOnLine(gosub.targetLogicalLine)
+        if gosub_target:
+            self.__entry_points["gosub%d" % int(gosub.targetLogicalLine.value)] = gosub_target
+            gosub_target.entryPoint = "private"
+            gosub_target.addComeFromGosubEdge(gosub)
+        else:
+            print("Line not found")
+            # TODO: Error!
+            pass
+        
+    

owl_basic/flow/flow_analysis.py

@@ -0,0 +1,56 @@
+# Functions for analysing the CFG graph
+
+from owl_basic.syntax import ast
+
+
+def tagNode(tag, node):
+    if tag not in node.entryPoints:
+        node.addEntryPoint(tag)
+        tagFollowingStatements(node, tag)
+
+def tagSuccessors(entry_point, line_mapper):
+    """
+    Given an entry point node, tag all successors of that entry point
+    with the routine name
+    :param entry_point: A node which is the entry point into a routine
+    :param line_mapper: An object which supports a physicalToLogical method call
+                        to convert line numbers.
+    """
+    tag = None
+    if isinstance(entry_point, ast.DefineProcedure):
+        # TODO: There is a bug here, whereby SUBXYZ can get relabelled PROCSUBXYZ
+        tag = "PROC" + entry_point.name
+    elif isinstance(entry_point, ast.DefineFunction):
+        tag = "FN" + entry_point.name
+    elif len(entry_point.comeFromGosubEdges) != 0:
+        logical_line_number = line_mapper.physicalToLogical(entry_point.lineNum)
+        tag = "SUB%d" % logical_line_number
+    else:
+        # TODO: Find a better way to do this rather than defaulting here
+        tag = "MAIN"
+    
+    if tag is not None:
+        tagNode(tag, entry_point)
+        tagFollowingStatements(entry_point, tag)
+    
+def tagFollowingStatements(node, tag):
+    for successor in node.outEdges:
+        tagNode(tag, successor)
+
+def deTagSuccessors(node):
+    """
+    Given a node and its entry point tags, remove all those tags from following
+    the nodes.
+    """
+    tags = node.entryPoints
+    if tags is not None:
+        deTagFollowingStatements(node, tags)
+    
+def deTagFollowingStatements(node, tags):
+    for successor in node.outEdges:
+        deTagNode(tags, successor)
+        
+def deTagNode(tags, node):
+    if tags.issubset(node.entryPoints):
+        node.entryPoints.difference_update(tags)
+        deTagFollowingStatements(node, tags)

owl_basic/flow/flow_graph_creator.py

@@ -0,0 +1,14 @@
+'''
+Creation of the forward control flow graph
+'''
+
+import logging
+
+from .flowgraph_visitor import FlowgraphForwardVisitor
+
+logger = logging.getLogger('flow.flow_graph_creator')
+
+def createForwardControlFlowGraph(parse_tree, line_mapper, options):
+    logger.debug("flowgraph")
+    logger.info("Creating Control Flow Graph...")
+    parse_tree.accept(FlowgraphForwardVisitor(line_mapper))

owl_basic/flow/flowgraph_visitor.py

@@ -0,0 +1,178 @@
+import logging
+
+from owl_basic.visitor import Visitor
+from owl_basic.ast_utils import findFollowingStatement
+from .connectors import connect, connectToFollowing
+from owl_basic import errors
+
+logger = logging.getLogger('flow.flowgraph_visitor')
+
+class FlowgraphForwardVisitor(Visitor):
+    """
+    This visitor connects each statement node to its following statement node.
+    For composite statement nodes (e.g. Program, If or Case nodes) the visitor connects
+    the child nodes appropriately.
+    """
+    
+    def __init__(self, line_mapper):
+        self.line_mapper = line_mapper
+               
+    def visitAstNode(self, node):
+        "Visit all children in order"
+        node.forEachChild(self.visit)
+                                
+    def visitAstStatement(self, statement):
+        """
+        Default behaviour for statements is to insert into the graph
+        and connect to the following statement. We override this behaviour
+        for conditional statements with more specific visitors.
+        """
+        connectToFollowing(statement)
+    
+    def visitIf(self, iff):
+        """
+        Connect the If to the initial statements of the true and false
+        clauses.  Process each statement in both clauses.
+        """
+        following = findFollowingStatement(iff)
+        if not following:
+            errors.internal("Following statement to IF not found at line %d" % iff.lineNum)
+        if iff.trueClause is not None:
+            if isinstance(iff.trueClause, list):
+                if len(iff.trueClause) > 0:
+                    # Connect to the beginning of the true clause
+                    first_true_statement = iff.trueClause[0]
+                    connect(iff, first_true_statement)
+                    
+                    for statement in iff.trueClause:
+                        self.visit(statement)
+                else:
+                    connect(iff.following) # TODO: Error!
+            else:
+                connect(iff, iff.trueClause)
+                self.visit(iff.trueClause)                
+        else:
+            connect(iff, following)
+                
+        if iff.falseClause is not None:
+            if isinstance(iff.falseClause, list):
+                if len(iff.falseClause) > 0:
+                    # Connect to the beginning of the false clause
+                    first_false_statement = iff.falseClause[0]
+                    connect(iff, first_false_statement)
+                    
+                    for statement in iff.falseClause:
+                        self.visit(statement)
+                else:
+                    connect(iff.following) # TODO: Error!
+            else:
+                connect(iff, iff.falseClause)
+                self.visit(iff.falseClause)
+        else:
+            connect(iff, following)       
+            
+    def visitGoto(self, goto):
+        """
+        Connect the Goto to the first statement on the target line if
+        it exists. Error if it does not.
+        """
+        # TODO: targetLogicalLine needs to be a constant for this
+        # to work
+        #print "CFG goto"
+        logger.debug("visitGoto")
+        #print "goto.targetLogicalLine = %s" % goto.targetLogicalLine.value
+        goto_target = self.line_mapper.statementOnLine(goto.targetLogicalLine)
+        #print "goto_target = %s" % goto_target
+        if goto_target:
+            connect(goto, goto_target)
+        else:
+            errors.error("No such line %s at line %s" % (goto.targetLogicalLine.value, goto.lineNum))
+                    
+    def visitOnGoto(self, ongoto):
+        """
+        Connect the OnGoto to the first statement on each of the target lines
+        if they exist. Error if they do not. Also connect to the first line of
+        the out-of-range clause if present, and process each statement within
+        that clause.
+        """
+        logger.debug("visitOnGoto")
+        ongoto.targetStatements = [] # TODO: Fix this so it isn't a monkey patch!
+        for targetLogicalLine in ongoto.targetLogicalLines:
+            ongoto_target = self.line_mapper.statementOnLine(targetLogicalLine)
+            if ongoto_target:
+                connect(ongoto, ongoto_target)
+                ongoto.targetStatements.append(ongoto_target)
+            else:
+                errors.error("No such line %s at line %s" % (targetLogicalLine.value, ongoto.lineNum))
+        
+        first_else_statement = None    
+        if ongoto.outOfRangeClause is not None:
+            if isinstance(ongoto.outOfRangeClause, list):
+                if len(ongoto.outOfRangeClause) > 0:
+                    # Connect to the beginning of the else clause
+                    first_else_statement = ongoto.outOfRangeClause[0]
+                    connect(ongoto, first_else_statement)
+                    
+                    for statement in ongoto.outOfRangeClause:
+                        self.visit(statement)
+            else:
+                first_else_statement = ongoto.outOfRangeClause
+                connect(ongoto, ongoto.outOfRangeClause)
+                self.visit(ongoto.outOfRangeClause)
+        ongoto.outOfRangeStatement = first_else_statement  # TODO: Fix this so it isn't a monkey patch!
+
+        assert hasattr(ongoto, "targetStatements")
+        assert hasattr(ongoto, "outOfRangeStatement")
+            
+    def visitCase(self, case):
+        """
+        Connect the Case statement to the first statement of each when clause and
+        the otherwise clause. Process the statements within each clause.
+        """
+        logger.debug("visitCase")
+        for when_clause in case.whenClauses:
+            if when_clause.statements is not None and len(when_clause.statements) > 0:
+                # Connect to the beginning of the when clause
+                first_when_statement = when_clause.statements[0]
+                connect(case,first_when_statement)
+                
+                for statement in when_clause.statements:
+                    self.visit(statement)
+                                        
+    # The following are statements which do not pass control to the
+    # succeeding statement in the linear source code order of the program
+    
+    def visitReturnFromFunction(self, return_from_function):
+        # Do not connect to following statement
+        logger.debug("visitReturnFromFunction")
+
+    def visitReturnFromProcedure(self, return_frin_procedure):
+        # Do not connect to following statement
+        logger.debug("visitReturnFromProcedure")
+    
+    def visitGenerateError(self, generator_error):
+        # Do not connect to following statement
+        logger.debug("visitGenerateError")
+
+    def visitReturnError(self, return_error):
+        # Do not connect to following statement
+        logger.debug("visitReturnError")
+
+    def visitQuit(self, quit):
+        # Do not connect to following statement
+        logger.debug("visitQuit")
+
+    def visitStop(self, stop):
+        # Do not connect to following statement
+        logger.debug("visitStop")
+            
+    def visitEnd(self, end):
+        # Do not connect to following statement
+        logger.debug("visitEnd")
+
+    def visitReturn(self, end):
+        # Do not connect to following statement
+        # TODO: Rheolism!
+        logger.debug("visitReturn")
+    
+    

owl_basic/flow/longjump_converter.py

@@ -0,0 +1,20 @@
+'''
+Convert longjumps (GOTO out of a function or procedure)
+to exceptions with appropriate handlers.
+'''
+
+import logging
+
+from .longjump_visitor import LongjumpVisitor
+
+logger = logging.getLogger('flow.longjump_converter')
+
+def convertLongjumpsToExceptions(parse_tree, line_mapper, options):
+    logger.debug("convertLongjumpsToExceptions")
+    # Insert longjumps where flow control jumps out of a procedure
+    logging.info("Finding longjump locations")
+    ljv = LongjumpVisitor(line_mapper)
+    parse_tree.accept(ljv)
+    logging.info("Creating long jumps")
+        
+    ljv.createLongjumps()

owl_basic/flow/longjump_visitor.py

@@ -0,0 +1,53 @@
+# A visitor for locating longjumps
+
+from owl_basic.visitor import Visitor
+from owl_basic import errors
+from owl_basic.utility import underscoresToCamelCase
+from owl_basic.syntax.ast import Goto, LongJump
+from owl_basic.ast_utils import elideNode
+from . import flow_analysis
+
+class LongjumpVisitor(Visitor):
+    """
+    AST visitor for locating long jumps (jumps out of
+    procedures or functions) and replacing GOTOs with LONGJUMPs
+    """
+    def __init__(self, line_mapper):
+        self.line_mapper = line_mapper
+        self.longjumps = []
+        
+    def visitAstNode(self, node):
+        node.forEachChild(self.visit)
+    
+    def visitCfgVertex(self, vertex):
+        "Generic visitor for simple statements"
+        
+        # Check the entry points
+        for following in vertex.outEdges:
+            if len(vertex.entryPoints) > 0:
+                # Not unreachable code
+                if following.entryPoints != vertex.entryPoints:
+                    if isinstance(vertex, Goto):
+                        self.longjumps.append(vertex)
+            else:
+                # TODO: Improve error message
+                errors.warning("Unreachable statement at line %s" % vertex.lineNum)
+
+        vertex.forEachChild(self.visit)      
+        
+    def createLongjumps(self):
+        """
+        Iterate through the discovered long jump locations, modify entry point
+        tags in the following statements, replace Goto nodes with Longjump nodes
+        and modify the control flow graph.
+        """
+        #print "createLongjumps"
+        for node in self.longjumps:
+            flow_analysis.deTagSuccessors(node)
+            
+        for node in self.longjumps:
+            node.__class__ = LongJump
+            for target in node.outEdges:
+                target.inEdges.remove(node)
+            node.clearOutEdges()
+        

owl_basic/flow/subroutine_converter.py

@@ -0,0 +1,38 @@
+'''
+Convert subroutines with named PROCedures
+'''
+
+import logging
+
+from owl_basic.syntax.ast import DefineProcedure
+from owl_basic.ast_utils import insertStatementBefore
+from .convert_sub_visitor import ConvertSubVisitor
+from .flow_analysis import tagSuccessors, deTagSuccessors
+
+logger = logging.getLogger('flow.subroutine_converter')
+
+def convertSubroutinesToProcedures(parse_tree, entry_points, line_mapper, options):
+    logger.info("Convert subroutines to procedures")   
+    entry_point_names_to_remove = []
+    entry_points_to_add = {}
+    for name, entry_point in entry_points.items():
+        # TODO: This will only work with simple (i.e. single entry) subroutines
+        print("name = %s, entry_point = %s" % (name, entry_point))
+        subname = iter(entry_point.entryPoints).next()
+        if subname.startswith('SUB'):
+            procname = 'PROCSub' + subname[3:]
+            assert len(entry_point.inEdges) == 0
+            defproc = DefineProcedure(name=procname, formalParameters=None)
+            insertStatementBefore(entry_point, defproc)
+            deTagSuccessors(entry_point)
+            entry_point.clearEntryPoints()
+            entry_point_names_to_remove.append(name)
+            entry_points_to_add[procname] = defproc
+            entry_point.clearComeFromGosubEdges()
+            tagSuccessors(defproc, line_mapper)
+    for name in entry_point_names_to_remove:
+        del entry_points[name]
+    entry_points.update(entry_points_to_add)
+    
+    csv = ConvertSubVisitor()
+    parse_tree.accept(csv)

owl_basic/flow/traversal.py

@@ -0,0 +1,110 @@
+'''
+Algorithms for traversal of the control flow graph
+'''
+
+import logging
+from itertools import chain
+
+logger = logging.getLogger('flow.traversal')
+
+def depthFirstSearch(vertex, visited = None):
+    '''
+    A generator which performs depth first search from the supplied vertex through
+    the control flow graph.
+    :param vertex: A CFG Vertex from which depth first search will be performed
+    :param visited: A, optional set of vertices which need not be visited
+    :yields: Successive CfgVertices in a depth first traversal of the graph
+    '''
+    to_visit = []
+    if visited is None:
+        visited = set()
+    to_visit.append(vertex)
+    while len(to_visit) != 0:
+        v = to_visit.pop()
+        if v not in visited:
+            visited.add(v)
+            yield v
+            to_visit.extend(v.outEdges)
+
+class ApproximateToplogicalOrderer(object):
+    
+    def __init__(self, vertex, vertices_to_consider):
+        self.order = []
+        self.stack = []
+        self.cur_dfsnum = 0
+        self.index = {}
+        self.low = {}
+        self.vertices_to_consider = vertices_to_consider
+           
+        for v in self.vertices_to_consider:
+            self.index[v] = "To be done"
+            
+        # Special case the start vertex to prevent infinite recursion
+        self.index[vertex] = "Done"
+        for successor in chain(vertex.outEdges, vertex.loopBackEdges):
+            if successor in self.vertices_to_consider:
+                if self.index[successor] == "To be done":
+                    self.visit(successor)
+        self.order.insert(0, vertex)
+        
+    def visit(self, cur_vertex):
+        self.index[cur_vertex] = self.cur_dfsnum
+        self.low[cur_vertex] = self.cur_dfsnum
+        self.cur_dfsnum += 1
+        self.stack.append(cur_vertex)
+        
+        for successor in chain(cur_vertex.outEdges, cur_vertex.loopBackEdges):
+            if successor in self.vertices_to_consider:
+                if self.index[successor] == "To be done":
+                    self.visit(successor)
+                    self.low[cur_vertex] = min(self.low[cur_vertex], self.low[successor])
+                elif self.index[successor] == "Done":
+                    pass
+                
+                #else:
+                elif successor in self.stack:
+                    self.low[cur_vertex] = min(self.low[cur_vertex], self.index[successor])
+                    
+        if self.low[cur_vertex] == self.index[cur_vertex]:
+            # We found a strongly connected component
+            scc = []
+            while True:
+                popped = self.stack.pop()
+                scc.append(popped)
+                self.index[popped] = "Done"
+                if popped == cur_vertex:
+                    break
+                
+            if len(scc) == 1:
+                self.order.insert(0, cur_vertex)
+            else:
+                self.order = approximateTopologicalOrder(self.chooseFirst(scc), scc) + self.order
+        
+    def chooseFirst(self, scc):
+        '''
+        Returns the vertex with the most in edges which are not in scc. This function
+        is used for computing a likely starting point for the SCC.
+        :param scc: A list of vertices comprising a strong-connected-component.
+        '''
+        sizes = [v.inDegree for v in scc]
+        index = sizes.index(max(sizes))
+        return scc[index]
+
+def approximateTopologicalOrder(vertex, vertices_to_consider=None):
+    '''
+    A function which performs approximate topological ordering of the vertices
+    reachable from the supplied vertices, taking into account strongly
+    connected components in the graph.
+    :param vertex: The starting CfgVertex
+    :param vertices_to_consider: A set of vertices to which the search should be limited. If None, all vertices
+                                 reachable from vertex are used.
+    :returns A sequence of basic blocks in approximate toplogical order
+    '''
+    logger.debug("approximateTopologicalOrder(%s, %s)", str(vertex), str(vertices_to_consider))
+    vertices_under_consideration = set(depthFirstSearch(vertex)) if vertices_to_consider is None else vertices_to_consider
+    ato = ApproximateToplogicalOrderer(vertex, vertices_under_consideration)
+    assert set(ato.order) == set(vertices_under_consideration)
+    return ato.order
+
+               
+