owl-basic 0.6.0__py3-none-any.whl

owl_basic/correlation_visitor.py

@@ -0,0 +1,119 @@
+import logging
+from owl_basic import errors
+from collections import deque
+from owl_basic.syntax.ast import Repeat, While, ForToStep
+from owl_basic.flow.connectors import connectLoop
+from owl_basic.visitor import Visitor
+
+class CorrelationVisitor(Visitor):
+    """
+    This visitor performs abstract execution of the control-flow-graph in order
+    to correlate the opening and closing statements or FOR..NEXT, REPEAT..UNTIL
+    and WHILE..ENDWHILE loops.
+    
+    CFG nodes where execution branches are annotated with the current stack of
+    loop structures, and a depth first search is performed through the CFG.
+    If the stack is non-empty when a terminal node (no out-edges) is encountered
+    an error is reported.  If loops are incorrectly nested an error is reported.
+    If loops are correctly nested, back-edges are inserted into the CFG.
+    """
+    
+    def __init__(self):
+        self.to_visit = deque()
+        self.visited = set()
+        self.loops = [] # A stack for tracking the current abstract execution state
+
+    def start(self, entry_point):
+        """
+        The entry-point from which loop correlation should start
+        """
+        self.depthFirstSearch(entry_point)
+        for v in self.visited:
+            if hasattr(v, "loop_stack"):
+                del v.loop_stack
+
+    def depthFirstSearch(self, entry_point):
+        self.to_visit.append(entry_point)
+        while len(self.to_visit):
+            v = self.to_visit.pop()
+            # Restore the loop stack
+            if hasattr(v, "loop_stack"):
+                self.loops = v.loop_stack[:]
+            if v not in self.visited:
+                self.visited.add(v)
+                v.accept(self)
+                if len(v.outEdges) == 0 and len(self.loops) != 0:
+                    # TODO: Improve this error message by printing an
+                    # abstract stack trace
+                    errors.fatalError("In loops at terminal statement at line %s" % v.lineNum)
+                # If execution splits, take a copy of the current loop stack
+                # and store a reference to it on each of the target nodes of
+                # the out edges of the current node, so the state can be
+                # restored later in the traversal
+                if len(v.outEdges) > 1:
+                    loop_stack = self.loops[:]
+                    for target in v.outEdges:
+                        target.loop_stack = loop_stack
+                self.to_visit.extend(v.outEdges)
+
+    def visitAstStatement(self, statement):
+        """
+        Do nothing for most AST statements
+        """
+        pass
+    
+    def visitRepeat(self, repeat_stmt):
+        self.loops.append(repeat_stmt)
+        
+    def visitUntil(self, until_stmt):
+        if len(self.loops) == 0:
+            errors.fatalError("Not in a REPEAT loop at line %d." % until_stmt.lineNum)
+        peek = self.loops[-1]
+        if not isinstance(peek, Repeat):
+            errors.fatalError("Not in a REPEAT loop at line %d; currently in %s loop opened at line %d" % (until_stmt.lineNum, peek.description, peek.lineNum))
+        repeat_stmt = self.loops.pop()
+        connectLoop(until_stmt, repeat_stmt)
+        
+    def visitWhile(self, while_stmt):
+        self.loops.append(while_stmt)
+        
+    def visitEndwhile(self, endwhile_stmt):
+        if len(self.loops) == 0:
+            errors.fatalError("Not in a WHILE loop at line %d." % endwhile_stmt.lineNum)
+        peek = self.loops[-1]
+        if not isinstance(peek, While):
+            errors.fatalError("Not in a WHILE loop at line %d; currently in %s loop opened at line %d" % (endwhile_stmt.lineNum, peek.description, peek.lineNum))
+        while_stmt = self.loops.pop()
+        connectLoop(endwhile_stmt, while_stmt)
+        
+    def visitForToStep(self, for_stmt):
+        self.loops.append(for_stmt)
+        
+    def visitNext(self, next_stmt):
+        logging.debug("NEXT statement = %s", next_stmt)
+        #logging.debug("NEXT identifiers = %s", next_stmt.identifiers[0].identifier)
+        while True:
+            if len(self.loops) == 0:
+                errors.fatalError("Not in a FOR loop at line %d." % next_stmt.lineNum)
+            peek = self.loops[-1]
+            if not isinstance(peek, ForToStep):
+                errors.fatalError("Not in a FOR loop at line %d; currently in %s loop opened at line %d" % (next_stmt.lineNum, peek.description, peek.lineNum))
+            
+            for_stmt = self.loops.pop()
+            # If the next_stmt has no attached identifiers, it applies to the
+            # top FOR statement on the stack
+            if len(next_stmt.identifiers) == 0:
+                 next_stmt.identifiers.append(for_stmt.identifier)
+            id1 = for_stmt.identifier.identifier
+            print(next_stmt.identifiers)
+            id2 = next_stmt.identifiers[0].identifier
+            print("self.loops = ", self.loops)
+            print("id1 = ", id1)
+            print("id2 = ", id2)
+            # TODO: Check that the symbols are equal, not just the names
+            if for_stmt.identifier.identifier == next_stmt.identifiers[0].identifier:
+                connectLoop(next_stmt, for_stmt)
+                break    
+    
+        
+        

owl_basic/data_visitor.py

@@ -0,0 +1,62 @@
+import logging
+import re
+from owl_basic.visitor import Visitor
+
+class DataVisitor(Visitor):
+    '''
+    Extra DATA from DATA statements and hidden DATA within REM statements.
+    BBC BASIC allows any line to be RESTOREd to and will attempt to READ data
+    from either the first DATA statement or the first COMMA.  This means it
+    is possible to do
+    10 REM,"HELLO", "WORLD"
+    20 RESTORE 10
+    30 READ A$
+    40 PRINT A$
+    > RUN
+    HELLO
+    
+    For this reason, we need to store anything following a COMMA in a REM
+    statement.  Any DATA keyword following a REM is irrelevant since it will
+    not be tokenized, reading will start from the first COMMA.
+    
+    It is NOT possible to READ into a REMed data block from a previous DATA
+    statement; the REMed line must be RESTOREd to directly
+    '''
+    def __init__(self):
+        self.data = []
+        self.index = {} # physical 0-based line number -> data[index]
+
+    def parse(self, data):
+        "Parse the text following a DATA statement into items"
+        # Break the data into fields
+        raw_items = re.findall(r'(?:\s*"((?:[^"]+|"")*)"(?!")\s*)|([^,]+)', data)
+        items = []
+        for i, (quoted, unquoted) in enumerate(raw_items):
+            if quoted:
+                item = quoted.replace('""', '"')
+            else:
+                item = unquoted.lstrip()
+                # If its the last item on the line, strip trailing space
+                if i == len(raw_items) - 1:
+                    item = item.rstrip()
+            items.append(item)
+        return items
+    
+    def visitAstNode(self, node):
+        node.forEachChild(self.visit)
+    
+    def visitData(self, statement):
+       logging.debug("DATA statement : %s" % statement.data)
+       self.index[statement.lineNum] = len(self.data)
+       items = self.parse(statement.data)
+       self.data.extend(items)
+       
+    def visitRem(self, statement):
+        logging.debug("REM statement : %s" % statement.data)
+        # Find the index of the first comma
+        comma_index = statement.data.find(',')
+        if comma_index != -1:
+            # A comma was found, so it is possible to RESTORE to this line
+            self.index[statement.lineNum] = len(self.data)
+            items = self.parse(statement.data[comma_index+1:])
+            self.data.extend(items)

owl_basic/decoder.py

@@ -0,0 +1,339 @@
+#!/usr/bin/env python
+#
+# (c) 2007 Matt Godbolt.
+#
+# Updated 2008 Ian Smallshire.
+#
+# Get v0.01 @ http://xania.org/200711/bbc-basic-v-format
+#
+# Use however you like, as long as you put credit where credit's due.
+# Some information obtained from source code from RISC OS Open.
+# v0.01 - first release.  Doesn't deal with GOTO line numbers.       (c) 2007 Matt Godbolt
+# v0.02 - edited to output line numbers where needed and fixed       Ian Smallshire
+#         the GOTO/RESTORE/GOSUB line numbers.
+# v0.03 - Added file type detection for input and provision          Ian Smallshire
+#         for BB4W encoded tokens
+# v0.04 - Now decodes BB4W tokens as well as Acorn.                  Ian Smallshire
+# v0.05 - Corrected tokens inside strings. No longer detokenized     Rob & Ian Smallshire
+# v0.06 - Fixed line number decoding with line numbers over 32767    Ian Smallshire
+
+#line numbers for bb4w still need testing properly.
+#if input file is plane text it must be terminated by an EOL
+import struct, re, getopt, sys
+
+# The list of BBC BASIC V tokens:
+# Base tokens, starting at 0x7f
+
+class Decoder(object):
+    
+    def __init__(self, data):
+        self.data = data
+        self.lines = []
+        
+    #data = property(lambda self: self.__data)
+        
+class PlainTextDecoder(Decoder):
+    
+    def __init__(self, data):
+        super(PlainTextDecoder, self).__init__(data)
+        
+    def decode(self):
+        split_lines = self.data.split(self.lineEnd)
+        
+        # Remove any trailing empty line
+        if len(split_lines[-1]) == 0:
+            split_lines = split_lines[:-1]
+            
+        has_line_numbers = None # Tri-state None, True or False
+        logical_line_number = 10
+        
+        for line in split_lines:
+            m = re.match(r'\s*(\d+)?\s?(.*)', line) # TODO: Factor this regex out of here and decoder
+            line_number, line_body = m.group(1), m.group(2)
+            current_line_has_number = line_number is not None
+            
+            if has_line_numbers is None:
+                has_line_numbers = current_line_has_number
+            else:
+                if current_line_has_number != has_line_numbers:
+                    raise Exception("Inconsistent line numbering") 
+            
+            # Fake line numbers if they are missing
+            if has_line_numbers == False:
+                line_number = logical_line_number
+                
+            logical_line_number += 10
+                            
+            self.lines.append((line_number, line_body))
+            
+        return self.lines
+
+class PlainTextCrDecoder(PlainTextDecoder):
+    lineEnd = '\x0d'
+    fileTypeName = 'plain text CR'
+
+    def __init__(self, data):
+        super(PlainTextCrDecoder, self).__init__(data)
+
+class PlainTextLfDecoder(PlainTextDecoder):
+    lineEnd = '\x0a'
+    fileTypeName = 'plain text LF'
+    
+    def __init__(self, data):
+        super(PlainTextLfDecoder, self).__init__(data)
+
+class PlainTextLfCrDecoder(PlainTextDecoder):
+    lineEnd = '\x0a\x0d'
+    fileTypeName = 'plain text LFCR'
+    
+    def __init__(self, data):
+        super(PlainTextLfCrDecoder, self).__init__(data)
+    
+class PlainTextCrLfDecoder(PlainTextDecoder):
+    lineEnd = '\x0d\x0a'
+    fileTypeName = 'plain text CRLF'
+    
+    def __init__(self, data):
+        super(PlainTextCrLfDecoder, self).__init__(data)
+
+class BbcBasicAcornDecoder(Decoder):
+    lineEnd = '\x0d'
+    fileTypeName = 'BBC BASIC (Acorn)'
+    
+    def __init__(self, data):
+        super(BbcBasicAcornDecoder, self).__init__(data)
+    
+    def decode(self):
+        lenLineEnd = len(self.lineEnd)
+        while True:
+            if len(self.data) < 2:
+                raise Exception("Bad program")
+            if self.data[1] == '\xff':
+                break
+            #  {<cr> <linehi> <linelo> <len> <text>} <cr> <ff>
+            lineNumber=(ord(self.data[2]) + (ord(self.data[1]) * 256))
+            length=ord(self.data[3])
+            lineData = self.data[4:length]
+            self.lines.append([lineNumber, self.detokenise(lineData)])
+            self.data = self.data[length:]
+            if len(self.data) <= len(self.lineEnd):
+                # may need to check what data is in last chars
+                # all tests have been ending tokens/CR/LF
+                break
+        return self.lines
+    
+    def detokenise(self, lineData):
+        # Acorn encoding
+        # This regular expression is essentially:
+        # Match a quoted string OR
+        #
+        # (Optional extension token) followed by
+        # (REM token followed by the rest of the line)
+        #     -- this ensures we don't detokenise the REM statement itself
+        # OR
+        # (Line number following token, with 3 characters in the range 64-127)
+        # OR
+        # (any token)
+        return re.sub(r'"(?:(?:[^"]+|"")*)"(?!")|( ?)([\xc6-\xc8])?(\xf4.*|\x8d[\x40-\x7f]{3}|[\x7f-\xff])',
+                      BbcBasicAcornDecoder.replaceFunc, lineData)
+    
+    @staticmethod
+    def replaceFunc(match):
+        if match.group().startswith('"'):
+            return match.group()
+        else:
+            prefix, ext, token = match.groups()
+            if len(prefix) == 0:
+                prefix = ' '
+            tokenOrd = ord(token[0])
+            if ext: # An extended opcode, CASE/WHILE/SYS etc
+                if ext == '\xc6':
+                    return cfnTokens[tokenOrd-0x8e]
+                if ext == '\xc7':
+                    return comTokens[tokenOrd-0x8e]
+                if ext == '\xc8':
+                    return stmtTokens[tokenOrd-0x8e]
+                raise Exception("Bad token")
+            else: # Normal token, plus any extra characters
+                if token[0] == '\x8d': # line number following token
+                    #decode the 24 bit line number
+                    return str(DecodeLineNo(token[1:]))
+                else:
+                    return prefix + tokens[tokenOrd - 127] + token[1:]
+
+class BbcBasic8086(Decoder):
+    lineEnd = '\x0d'
+    fileTypeName = 'BBC BASIC (80/86)'
+    
+    def __init__(self, data):
+        super(BbcBasic8086, self).__init__(data)
+        
+    def decode(self):
+        # TODO this needs testing 
+        # i have read somewhere that bb4w uses different tokens
+        # and also has diff line number formatting
+        # (http://bb4w.wikispaces.com/Format)
+        # {<len> <linelo> <linehi> <text> <cr>} <00> <ff> <ff>
+        lenLineEnd = len(self.lineEnd)
+        
+        while True:
+            # TODO check if order of bytes is correct
+            lineNumber=(ord(self.data[1]) + (ord(self.data[2]) * 256)) # line number bytes in different order
+            length=ord(self.data[0])
+            if lineNumber == -1:
+                break
+            lineData = self.data[3:length]
+            self.lines.append([lineNumber, self.detokenise(lineData)])
+            self.data = self.data[length:]
+            if len(self.data) <= len(self.lineEnd):
+                # may need to check what data is in last chars
+                # all tests have been ending tokens/CR/LF
+                break
+        return self.lines
+    
+    def detokenise(self, lineData):
+        # This uses BB4W encoding
+        # This regular expression is essentially:
+        # Match a quoted string OR
+        #
+        # (REM token followed by the rest of the line)
+        #     -- this ensures we don't detokenise the REM statement itself
+        # OR
+        # (Line number following token, with 3 characters in the range 64-127)
+        # OR
+        # (any token 127-255)
+        # OR
+        # (any token 0-15) TODO check if 16 is needed (EXIT) i think
+        return re.sub(r'"(?:(?:[^"]+|"")*)"(?!")|( ?)(\xf4.*|\x8d[\x40-\x7f]{3}|[\x7f-\xff]|[\x00-\x0f])',
+                      BbcBasic8086Decoder.replaceFunc, line)
+    
+    @staticmethod
+    def replaceFunc(match):
+        if match.group().startswith('"'):
+            return match.group()
+        else:
+            prefix, token = match.groups()
+            if len(prefix) == 0:
+                prefix = ' '
+            tokenOrd = ord(token[0])
+            if token[0] == '\x8d': # line number following token
+                #decode the 24 bit line number
+                return str(DecodeLineNo(token[1:]))
+            else:
+                return prefix + bb4wTokens[tokenOrd ^ 128] + token[1:]
+
+def fileType(data):
+    '''
+    Factory to produce the correct decoder depending on the file contents.
+    '''
+    if len(data) < 4:
+        # TODO unsure how you want to return error
+        raise Exception("Bad Program")
+    
+    fileExt = data[-4:]
+    
+    # Check final byte sequence (longest sequence first)
+    if fileExt == '\x0d\x00\xff\xff':
+        return BbcBasic8086Decoder(data)
+    elif fileExt[2:4] == '\x0a\x0d':
+        return PlainTextLfCrDecoder(data)  
+    elif fileExt[2:4] == '\x0d\x0a':
+        return PlainTextCrLfDecoder(data)
+    elif fileExt[2:4] == '\x0d\xff':
+        return BbcBasicAcornDecoder(data)
+    elif fileExt[3] == '\x0d':
+        return PlainTextCrDecoder(data);
+    elif fileExt[3] == '\x0a':
+        return PlainTextLfDecoder(data)
+    else:
+        raise Exception("Unrecognised program format")
+    
+tokens = [
+    'OTHERWISE', # 7f
+    'AND', 'DIV', 'EOR', 'MOD', 'OR', 'ERROR', 'LINE', 'OFF',
+    'STEP', 'SPC', 'TAB(', 'ELSE', 'THEN', '<line>' , 'OPENIN', 'PTR',
+    'PAGE', 'TIME', 'LOMEM', 'HIMEM', 'ABS', 'ACS', 'ADVAL', 'ASC',
+    'ASN', 'ATN', 'BGET', 'COS', 'COUNT', 'DEG', 'ERL', 'ERR',
+    'EVAL', 'EXP', 'EXT', 'FALSE', 'FN', 'GET', 'INKEY', 'INSTR(',
+    'INT', 'LEN', 'LN', 'LOG', 'NOT', 'OPENUP', 'OPENOUT', 'PI',
+    'POINT(', 'POS', 'RAD', 'RND', 'SGN', 'SIN', 'SQR', 'TAN',
+    'TO', 'TRUE', 'USR', 'VAL', 'VPOS', 'CHR$', 'GET$', 'INKEY$',
+    'LEFT$(', 'MID$(', 'RIGHT$(', 'STR$', 'STRING$(', 'EOF',
+    '<ESCFN>', '<ESCCOM>', '<ESCSTMT>',
+    'WHEN', 'OF', 'ENDCASE', 'ELSE', 'ENDIF', 'ENDWHILE', 'PTR',
+    'PAGE', 'TIME', 'LOMEM', 'HIMEM', 'SOUND', 'BPUT', 'CALL', 'CHAIN',
+    'CLEAR', 'CLOSE', 'CLG', 'CLS', 'DATA', 'DEF', 'DIM', 'DRAW',
+    'END', 'ENDPROC', 'ENVELOPE', 'FOR', 'GOSUB', 'GOTO', 'GCOL', 'IF',
+    'INPUT', 'LET', 'LOCAL', 'MODE', 'MOVE', 'NEXT', 'ON', 'VDU',
+    'PLOT', 'PRINT', 'PROC', 'READ', 'REM', 'REPEAT', 'REPORT', 'RESTORE',
+    'RETURN', 'RUN', 'STOP', 'COLOUR', 'TRACE', 'UNTIL', 'WIDTH', 'OSCLI']
+
+# Referred to as "ESCFN" tokens in the source, starting at 0x8e.
+cfnTokens = [
+    'SUM', 'BEAT']
+# Referred to as "ESCCOM" tokens in the source, starting at 0x8e.
+comTokens = [
+    'APPEND', 'AUTO', 'CRUNCH', 'DELETE', 'EDIT', 'HELP', 'LIST', 'LOAD',
+    'LVAR', 'NEW', 'OLD', 'RENUMBER', 'SAVE', 'TEXTLOAD', 'TEXTSAVE', 'TWIN'
+    'TWINO', 'INSTALL']
+# Referred to as "ESCSTMT", starting at 0x8e.
+stmtTokens= [
+    'CASE', 'CIRCLE', 'FILL', 'ORIGIN', 'PSET', 'RECT', 'SWAP', 'WHILE',
+    'WAIT', 'MOUSE', 'QUIT', 'SYS', 'INSTALL', 'LIBRARY', 'TINT', 'ELLIPSE',
+    'BEATS', 'TEMPO', 'VOICES', 'VOICE', 'STEREO', 'OVERLAY']
+# BB4W tokens....
+# these tokens start at 128 and wrap around to 0-15
+bb4wTokens=["AND","DIV","EOR","MOD","OR","ERROR","LINE","OFF",
+        "STEP","SPC","TAB(","ELSE","THEN","","OPENIN","PTR",
+        "PAGE","TIME","LOMEM","HIMEM","ABS","ACS","ADVAL","ASC",
+        "ASN","ATN","BGET","COS","COUNT","DEG","ERL","ERR",
+        "EVAL","EXP","EXT","FALSE","FN","GET","INKEY","INSTR(",
+        "INT","LEN","LN","LOG","NOT","OPENUP","OPENOUT","PI",
+        "POINT(","POS","RAD","RND","SGN","SIN","SQR","TAN",
+        "TO","TRUE","USR","VAL","VPOS","CHR$","GET$","INKEY$",
+        "LEFT$(","MID$(","RIGHT$(","STR$","STRING$(","EOF","SUM","WHILE",
+        "CASE","WHEN","OF","ENDCASE","OTHERWISE","ENDIF","ENDWHILE","PTR",
+        "PAGE","TIME","LOMEM","HIMEM","SOUND","BPUT","CALL","CHAIN",
+        "CLEAR","CLOSE","CLG","CLS","DATA","DEF","DIM","DRAW",
+        "END","ENDPROC","ENVELOPE","FOR","GOSUB","GOTO","GCOL","IF",
+        "INPUT","LET","LOCAL","MODE","MOVE","NEXT","ON","VDU",
+        "PLOT","PRINT","PROC","READ","REM","REPEAT","REPORT","RESTORE",
+        "RETURN","RUN","STOP","COLOUR","TRACE","UNTIL","WIDTH","OSCLI",
+        "","CIRCLE","ELLIPSE","FILL","MOUSE","ORIGIN","QUIT","RECTANGLE",
+        "SWAP","SYS","TINT","WAIT","INSTALL","","PRIVATE","BY","EXIT"]
+
+def DecodeLineNo(lineNo):
+    """Returns a line number from a 24bit encoded line number"""
+    byte0=ord(lineNo[0])
+    byte1=ord(lineNo[1])
+    byte2=ord(lineNo[2])
+    #needed to be ANDed with 255 after multiply because with this formula
+    #on the 6502 it moved the high bits to carry with the Logical Shift 
+    msb = byte2 ^ (( byte0 * 16) & 255)          
+    lsb = byte1 ^ (((byte0 & 0x30 ) * 4) & 255)  
+    return (lsb + (msb * 256))
+
+def ReadLines(data):
+    """Returns a list of [line number, tokenised line] from a binary
+       BBC BASIC format file."""
+    decoder = fileType(data)
+    lines = decoder.decode()
+    return lines
+    
+def decode(data, output):
+    """Decode binary data 'data' and write the result to 'output'."""
+    lines = ReadLines(data)
+    for lineNumber, lineData in lines:
+        output.write(str(lineNumber) + ' ')
+        # Normalise line endings to \n
+        output.write(lineData.strip() + '\n')
+
+if __name__ == "__main__":
+    optlist, args = getopt.getopt(sys.argv[1:], '')
+    if len(args) != 2:
+        print("Usage: %s INPUT OUTPUT" % sys.argv[0])
+        sys.exit(1)
+    entireFile = open(args[0], 'rb').read()
+    output = open(args[1], 'w')
+    decode(entireFile, output)
+    output.close()

owl_basic/errors.py

@@ -0,0 +1,22 @@
+import sys
+import logging
+
+error_log = set()
+
+def warning(message):
+    if message not in error_log:
+        logging.warning(message)
+        error_log.add(message)
+    
+def error(message):
+    if message not in error_log:
+        logging.error(message)
+        error_log.add(message)
+
+def fatalError(message):
+    logging.critical(message)
+    sys.exit(1)
+    
+def internal(message):
+    logging.critical(message)
+    sys.exit(1)

owl_basic/flow/__init__.py

@@ -0,0 +1,17 @@
+'''
+Package for analysing and manipulating control flow.
+'''
+
+from .entry_point_locator import locateEntryPoints
+from .flow_graph_creator import createForwardControlFlowGraph
+from .longjump_converter import convertLongjumpsToExceptions
+from .subroutine_converter import convertSubroutinesToProcedures
+from .basic_block_identifier import identifyBasicBlocks
+from .basic_block_orderer import orderBasicBlocks
+
+__all__ = ["locateEntryPoints",
+           "createForwardControlFlowGraph",
+           "convertLongjumpsToExceptions",
+           "convertSubroutinesToProcedures",
+           "identifyBasicBlocks"]
+

owl_basic/flow/basic_block.py

@@ -0,0 +1,34 @@
+'''
+Created on 30 Jan 2010
+
+@author: rjs
+'''
+
+from owl_basic.cfg_vertex import CfgVertex
+
+class BasicBlock(CfgVertex):
+    '''
+    A sequence of statements with a single entry and exit point
+    '''
+
+    def __init__(self, statements=[], *args, **kwargs):
+        '''
+        :param statements: A list of statements comprising the basic block
+        '''
+        super(BasicBlock, self).__init__(*args, **kwargs)
+        self.statements = [] # The list of statements comprising the basic block
+        self.topological_order = None # Integer giving ordinal position in method
+        self.label = None # A label into which can be branched to, to enter this basic block
+        self.is_label_marked = False # A flag for whether the label has been marked
+        
+    ''' The first statement in the BasicBlock, or None'''
+    entryPoint = property(lambda self: self.statements[0] if len(self.statements) > 0 else None)
+    
+    '''The last statement in the BasicBlock, or None'''
+    exitPoint = property(lambda self: self.statements[-1] if len(self.statements) > 0 else None)
+    
+    def __len__(self):
+        return len(self.statements)
+    
+        
+        

owl_basic/flow/basic_block_identifier.py

@@ -0,0 +1,66 @@
+'''
+Grouping of statements into basic blocks - resulting in a coarser grained control flow graph
+'''
+import logging
+logger = logging.getLogger('flow.basic_block_identifier')
+logger.setLevel(logging.WARNING)
+
+from .connectors import connect
+from .traversal import depthFirstSearch
+from .basic_block import BasicBlock
+
+def identifyBasicBlocks(entry_points, options):
+    '''
+    Trace the control flow graph from each entry point and collect consecutive statements
+    into basic blocks, comprising a more coarse grained control flow graph. This function applies
+    a transformation to the statement level basic block, coarsening it by grouping statements into
+    a graph consisting only of BasicBlock instances.  Each BasicBlock instance contains a list of
+    non-branching, or non-branch target statements.
+    
+    A basic block is code that has one entry point (i.e., no code within it is the destination
+    of a jump instruction), one exit point and no jump instructions contained within it. The
+    start of a basic block may be jumped to from more than one location. The end of a basic block
+    may be a jump instruction or the statement before the destination of a jump instruction. Basic
+    blocks are usually the basic unit to which compiler optimizations are applied. Basic blocks
+    form the vertices or nodes in a control flow graph.
+    
+    :param entry_points: A sequence of program statements which are the entry point to the program
+                         or procedures
+    :param options:      Program options
+    :returns:            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
+    '''
+    logger.info("Identifying basic blocks")
+    print(entry_points)
+    return dict((k, coarsenControlFlowGraph(v)) for k, v in entry_points.items())
+        
+def coarsenControlFlowGraph(entry_point):
+    '''
+    Coarsen the control flow graph starting at the entry_point to consist of BasicBlocks
+    :param entry_point: A program statement which is the entry point to the program, procedure or function
+                        for which the control flow graph is to be coarsened to basic blocks.
+    :returns: The entry block BasicBlock instance corresponding to entry_point
+    '''
+    logger.debug("entry_point = %s", entry_point)
+    block = assignBlockAndContinue(entry_point)
+    return block
+
+# TODO: Decorate as a tail-call    
+def assignBlockAndContinue(vertex, block=None):
+    '''
+    Assign vertex to block and continue with successor vertices
+    '''
+    if not vertex.block:           
+        block = ((vertex.inDegree == 1) and block) or BasicBlock()
+        block.statements.append(vertex)
+        vertex.block = block
+        logger.debug("%s with in-degree %s and out-degree %s at %s in %s", vertex, str(vertex.inDegree), str(vertex.outDegree), str(vertex.lineNum), vertex.block)
+        for target in vertex.outEdges:
+            successor_block = assignBlockAndContinue(target, block if vertex.outDegree == 1 else None)
+            if block is not successor_block:
+                connect(block, successor_block)             
+    return vertex.block
+           
+    
+