blocks.py

Go to the documentation of this file.

##
# @file blocks.py
# @brief Contains the basic block class.
#
#............................................................................
# Copyright (c) 2009,2010,2011 David Car, david.car7@gmail.com
#
# This program is free software; you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free Software
# Foundation; either version 2 of the License, or (at your option) any later
# version.
#
# This program is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License along with
# this program; if not, write to the Free Software Foundation, Inc., 59 Temple
# Place, Suite 330, Boston, MA 02111-1307 USA
#..........................................................................
from funcs import *
from tables import SymbolTable
from sets import ASet
from parsers import pyp
from time import time as sys_time
import os
import re
import hashlib
import copy
from math import log
from math import ceil

class Block(object):
    """This is the base block class.
    """

    #................................................................................
    # pyparsing grammars
    #................................................................................
    GRAMMAR = None
    SENTINEL = None
    CHILDTOKEN = None
    BLOCKTYPE='Block'
    #................................................................................

    def __init__(self, blockType, name, parent=None, childToken=None):
        self._parent = parent
        self._code = []
        self._children = SymbolTable()
        self._name = name
        self._blockType = blockType
        self._childDeps = ASet()
        self._ownDeps = ASet()
        self._childToken = childToken
        self._depList = []
        self._depIgnore = []
        self._state = None
        self._fromCache = False
        self._timeStamp = sys_time()

        #................................................................................
        # pyparsing grammars
        #................................................................................
        jc = self._children.joinCharacter()
        if self.SENTINEL is None:
            self.SENTINEL = \
                pyp.StringStart() +\
                pyp.CaselessKeyword('end') +\
                pyp.CaselessKeyword(self._blockType) +\
                pyp.CaselessKeyword(self._name)

        if childToken is None:
            self.CHILDTOKEN = \
                pyp.StringStart() +\
                pyp.Suppress(pyp.Literal('#')) +\
                pyp.Suppress(pyp.CaselessKeyword('Child:')) +\
                pyp.Word(pyp.alphas, pyp.alphanums+'_~<>=()'+jc)('symbol')

    def getTimeStamp( self ):
        """ Return the time stamp of the block.
        """
        return self._timeStamp
    
    def addLine( self, line, n=None ):
        '''Rudimentary method to add a line to the code listing of the block.

        '''
        self._code.append( line )

    def addDeps( self, sym, propagate=True ):
        '''Add an internal dependency and propagate up the tree.  Do not add
        dependencies that are resolved by any of your children.  This is
        checked by consulting the child nodes to see if they contain the
        dependency.  Call the addChildDeps() on the parent.  The dependency is
        given as a symbol name, not a set.

        '''
        if sym in self._depIgnore: return
        if self.contains(sym): return
        self._ownDeps.add(sym)
        if propagate and self._parent: self._parent.addChildDeps(sym)

    def addChildDeps( self, sym, propagate=True, skipList=None ):
        '''Add the dependencies from a child block to the _childDeps set.

        '''
        if sym in self._depIgnore: return
        if self.contains( sym, skipList ): return
        self._childDeps.add( sym )
        if propagate and self._parent: 
            self._parent.addChildDeps( sym, propagate, skipList )

    def shareDeps( self, propagate=True ):
        '''Propagate the dependencies to the parent.  If propagate is True,
        then continue up the tree.

        '''
        parent = self._parent
        if parent:
            for sym in self.dependencies():
                parent.addChildDeps( sym, propagate, skipList=( self, ) )
        
    def contains( self, sym, skipList=None ):
        '''Search to see if block has symbol.

        '''
        if not self.isTemplated():
            # if self.resolveSymbol( sym ) in self._children:  return True
            if sym in self._children:  return True
            if skipList is not None:
                _children = [ x for x in self._children.values()
                              if x not in skipList ]
            else:
                _children = self._children.values()
            for child in _children:
                if child.contains( sym, skipList ): return True
        return False
            
    def addChild( self, blk, token=None, before=False, regen=True ):
        '''Add a block as a child of this block.  If a token string is given, then add
        this child as a token before/after this string in the code, else,
        just append it to the code at the end.

        Inputs
        ------
        blk : child block to add
        token : token string to use for adding line after/before
        before : boolean.  If true, add child line before given token; else after.

        '''
        addChildDeps = self.addChildDeps

        self._children.register( blk )
        blk.setParent( self, regen )
        blk.ignoreDependencies( self._depIgnore )
        blk.removeDependencies( self._depIgnore )

        #.................................................................
        # Check if this new child resolves any dependencies
        #.................................................................
        for sym in list( self._ownDeps ):
            if blk.contains( sym ):
                self._ownDeps.discard( sym )

        for sym in list( self._childDeps ):
            if blk.contains( sym ):
                self._childDeps.discard( sym )

        #............................................................
        # Now add the child dependencies to the parent
        #............................................................
        for sym in blk.dependencies():
            addChildDeps( sym )

        #............................................................
        # Add the child line after/before token
        #............................................................
        if token:
            try:
                n = self._code.index( token ) + 1
            except:
                n = None
        else:
            n = None

        self.addLine( self.childString( blk.name() ), n )

    def mergeChildren( self, tbl ):
        '''Merge a symbol table with children into the block and add their
        dependencies.  Does nothing to the underlying code base though.
        Useful only in certain circumstances.

        '''
        addChildDeps = self.addChildDeps
        for blk in tbl.values():
            self._children.register( blk )
            for sym in blk.dependencies():
                addChildDeps( dep )

    def setParent(self, blk, regen=True):
        '''Set the parent block for this block.  If this block has a parent,
        remove it from that blocks children.

        '''
        if self._parent is blk:  return

        if self._parent:
            self._parent.popChild( self.name(), regen )

        self._parent = blk

#     def setChild(self, blk):
#         '''Add a child block to this block, but does not touch the code like the
#         addChild(...) method does.  It simply puts the child into this blocks
#         local symbolTable (_children).

#         '''
#         self._children.register(blk)

    def popChild(self, name, regen=True):
        '''Remove a child from this block.

        '''
        self._code.remove( self.childString( name ) )
        child = self._children.pop( name )
        if regen: self.regenChildDeps()
        return child

    def regenChildDeps( self ):
        '''Clear the child dependency list and regenerate it from the children.

        '''
        self._childDeps.clear()
        for blk in self._children.values():
            for dep in blk.dependencies():
                self.addChildDeps( dep, propagate=False )
        
        if self._parent: self._parent.regenChildDeps()

    def baseName( self ):
        '''Return the base, i.e. non-instantiated, non-mangled, name of the block.

        '''
        return self._name

    @staticmethod
    def childString( name ):
        '''Create a child string token.

        '''
        return '# Child: %s%s' %( name, os.linesep )

    def name( self ):
        '''Return the name of the block.

        '''
        return self._name

    def blockType(self):
        return self._blockType

    def sentinel(self, line):
        if self.SENTINEL is None: return False
        if self.SENTINEL.searchString(line):
            self.addLine(line)
            return True
        return False

    def children(self):
        return self._children

    def dependencies(self):
        return self._ownDeps.union(self._childDeps)

    def clearChildDependencies( self ):
        self._childDeps.clear()

    def clearOwnDependencies( self ):
        self._ownDeps.clear()

    def clearAllDependencies( self ):
        self.clearChildDependencies()
        self.clearOwnDependencies()

    def renameDependencies( self, nameMap ):
        '''Rename an existing dependency in the dependency list and propagate
        to the children.

        '''
        if isinstance( nameMap, list ):
            for oldName,newName in nameMap:
                self._ownDeps.discard( oldName )
                self._ownDeps.add( newName )
                if oldName in self._childDeps:
                    self._childDeps.discard( oldName )
                    self._childDeps.add( newName )

            for child in self._children:
                child.renameDependency( nameMap )
        else:
            oldName, newName = nameMap
            self._ownDeps.discard( oldName )
            self._ownDeps.add( newName )
            if oldName in self._childDeps:
                self._childDeps.discard( oldName )
                self._childDeps.add( newName )

            for child in self._children:
                child.renameDependency( oldName, newName )
            
    def removeDependencies( self, depList ):
        '''Remove a list of token dependencies from both dependencies lists
        and traverse down the tree recursively to the children and do the
        same.
        '''
        for dep in depList:
            self._ownDeps.discard( dep )
            self._childDeps.discard( dep )
        for child in self._children.values():
            child.removeDependencies( depList )

    def ignoreDependencies( self, depList ):
        '''A list of dependencies that should be ignored.

        '''
        self._depIgnore = copy.copy( depList )
        for child in self._children.values():
            child.ignoreDependencies( depList )

    def getIgnoreDependencies( self ):
        return copy.copy( self._depIgnore )

    def parent(self):
        return self._parent
    
    def hasChild(self, blk):
        return (blk.name() in self._children)

    def root(self):
        '''Return the root of the block tree starting at this block.

        '''
        if self._parent:
            return self._parent.root()
        return self

    def upTo(self, blkType):
        '''Travel up the tree and return the first blkType found in this
        blocks lineage.

        '''
        if isinstance(self, blkType): return self
        if self._parent:
            return self._parent.upTo(blkType)
        return None
        
    def objects(self):
        return self._objects

    def code(self, lineNumbers=False):
        '''Show the code strings with or without line numbers.  The default is
        no line numbers.

        '''
        block = ''
        _srcLength = int(ceil(log(len(self._code)+1)/log(10)))
        if lineNumbers:
            for n,line in enumerate(self._code):
                block += "%s %s%s"%(str(n).zfill(_srcLength+1),line.rstrip(), os.linesep)
        else:
            for line in self._code:
                block += line.rstrip()+os.linesep

        return block

    def codeList(self):
        return self._code

    def show(self):
        '''Show the block unrolled.

        '''
        block = ''
        for line in self._code:
            child = self.CHILDTOKEN.searchString(line)
            if child:
                sym = child[0].symbol
                _blk = self._children.get(sym, None)
                if _blk is None:
                    print 'Child %s has disappeared from block %s'%(sym, self.name())
                    line = ''
                else:
                    line = _blk.show()
            block += line
        return block

    def hash(self):
        '''Return a hashed value of this block if it does not already have a
        _hash internal value.  Uses the mangled version for the hash.

        '''
        hsh = getattr(self, '_hash', None)
        if hsh is None:
            self._hash = hashlib.sha256(self.show(True)).hexdigest()
        return self._hash
    
    def __getstate__(self, _dd=None):
        '''Builds a dictionary tree of the block for pickling.

        '''
        if _dd is None: _dd = self.__dict__.copy()
        _dd.pop('_children', None)
        _dd.pop('_parent', None)
        _dd.pop('SENTINEL', None)
        _dd.pop('CHILDTOKEN', None)
        _dd['_children'] = []

        for child in self.children().values():
            _dd['_children'].append( child.__getstate__() )
        return _dd

    def __setstate__(self, tree):
        '''Unpack the dictionary tree.

        '''
        g = globals()
        self.__dict__.update( tree )
        _children = self._children
        self._children = SymbolTable()

        for node in _children:
            _blockType = node[ '_blockType' ]
            _params = node[ '_parameters' ]
            child = g[ _blockType ]( _params )
            child.__setstate__( node )
            child.setParent( self )
            self._children.register( child )

    def unserialize(self, tree):
        self.__setstate__(tree)

    def serialize(self, _dd=None):
        '''Builds a dictionary tree of the block.

        '''
        return self.__getattr__(_dd)

    def toFile(self, name):
        '''Write the block to a special file.  This will write everything
        necessary to recreate the block and all its children with the fromFile
        class method.

        Input
        -----
        name : block fileName to write it to

        '''
        
        # Save the internal dictionary
        import pickle

        tree = self.getDictTree()
        hsh = getattr('_hash',None)

        output = open(name+'.pkl','wb')
        
        # Dump the hash value and the dictionary tree
        pickle.dump((self.hash(), tree), output)
        output.close()

    def lineArtGraph(self, tree=None):
        '''Display a line art graph for this block or the provided block tree.

        '''
        def _lineArtGraph(dt, tb=0):
            parent = dt
            if tb == 0:
                print parent['_blockType']+': '+parent['_name']
            else:
                print (tb-1)*(5*' ')+'|___ '+parent['_blockType']+': '+parent['_name']

            for child in parent[ '_children' ]:
                # print tb*'  '+'|'
                _lineArtGraph(child, tb+1)

        _tree = tree or self.__getstate__()
        _lineArtGraph(_tree)

    def findAll(self, blks, depth=-1):
        '''Find all types given in the blks tuple in your descendants to the
        given depth.  If depth is < 0 , then recurse all the way to the
        leaves.

        '''
        #............................................................
        def _findAll(myChildren, blks, matches, depth):

            if depth == 0: return
            _depth = depth-1
            
            for child in myChildren.values():
                if isinstance(child, blks):
                    matches.append(child)
                _findAll(child.children(), blks, matches, _depth)
        #............................................................

        matches = []
        _findAll(self.children(), blks, matches, depth)
        return matches

    def getFromCache(self):
        return self._fromCache

    def setFromCache(self, value):
        if isinstance(value, bool):
            self._fromCache = value
            if not value and self._parent: self._parent.fromCache = value
        else:
            print "fromCache must be a boolean type"

    #................................................................................
    # Virtual Methods
    #................................................................................
    def resolveSymbol(self, sym):
        raise NotImplementedError('''Virtual method 'resolveSymbol' in Block
        class''')

    def instantiate(self, obj):
        raise NotImplementedError("Virtual method 'instantiate' in Block class ")

    def getState(self):
        raise NotImplementedError("Virtual method 'getState' Block class")

    def setState(self, subs):
        raise NotImplementedError("Virtual function 'setState' in Block class")

    fromCache = property(getFromCache, setFromCache)