FileIncludeGraph

Captures the #include graph of a preprocessed file.

cpip.core.FileIncludeGraph.DUMMY_FILE_LINENUM = -1

In the graph the line number is ignored for dummy roots and this one used instead

cpip.core.FileIncludeGraph.DUMMY_FILE_NAME = None

The file ID for a ‘dummy’ file. This is used as the artificial root node for all the pre-includes and the ITU

exception cpip.core.FileIncludeGraph.ExceptionFileIncludeGraph

Simple specialisation of an exception class for the FileIncludeGraph classes.

exception cpip.core.FileIncludeGraph.ExceptionFileIncludeGraphRoot

Exception for issues for dummy file ID’s.

exception cpip.core.FileIncludeGraph.ExceptionFileIncludeGraphTokenCounter

Exception for issues for token counters.

class cpip.core.FileIncludeGraph.FigVisitorBase

Base class for visitors, see FigVisitorTreeNodeBase for base class for tree visitors.

__weakref__

list of weak references to the object (if defined)

visitGraph(theFigNode, theDepth, theLine)

Hierarchical visitor pattern. This is given a FileIncludeGraph as a graph node. theDepth is the current depth in the graph as an integer, theLine the line that is a non-monotonic sibling node ordinal.

class cpip.core.FileIncludeGraph.FigVisitorFileSet

Simple visitor that just collects the set of file IDs in the include graph and a count of how often they are seen.

fileNameMap

Dictionary of number of times each file is seen: {file : count, ...}.

Returns:dict({str : [int]}) – File count map.
fileNameSet

The set of file names seen.

visitGraph(theFigNode, theDepth, theLine)

Hierarchical visitor pattern.

Parameters:
Returns:

NoneType

class cpip.core.FileIncludeGraph.FigVisitorTree(theNodeClass)

This visitor can visit a graph of FileIncludeGraphRoot and FileIncludeGraph that recreates a tree of Node(s) the type of which are supplied by the user.

Each node instance will be constructed with either an instance of a FileIncludeGraphRoot or FileIncludeGraph or, in the case of a pseudo root node then None.

__init__(theNodeClass)

Constructor.

Parameters:theNodeClass (type) – The class of the visitor.
Returns:NoneType
__weakref__

list of weak references to the object (if defined)

_addAncestor()

Add an ancestor node.

Returns:NoneType
_addChild(theNode, theLine)

Add a child node.

Parameters:
  • theNode (cpip.core.FileIncludeGraph.FileIncludeGraph) – The node.
  • theLine (int) – Line number.
Returns:

NoneType

_addSibling(theNode, theLine)

Add a sibling.

Parameters:
Returns:

NoneType

depth

Returns the current depth in this graph representation. Changes to this determine if the node is a child, sibling or ancestor.

Returns:int – The depth.
tree()

Returns the top level node object as the only copy. This also finalises the tree.

Returns:cpip.IncGraphSVG.SVGTreeNodeMain – Top level node.
visitGraph(theFigNode, depth, line)

Visit the given node.

Parameters:
Returns:

NoneType

class cpip.core.FileIncludeGraph.FigVisitorTreeNodeBase(theLineNum)

Base class for nodes created by a tree visitor. See FigVisitorBase for the base class for non-tree visitors.

__init__(theLineNum)

Constructor.

Parameters:theLineNum (int) – The line number.
Returns:NoneType
__weakref__

list of weak references to the object (if defined)

addChild(theObj)

Add the object as a child node.

Parameters:theObj (cpip.IncGraphSVG.SVGTreeNodeMain) – The node.
Returns:NoneType
finalise()

This will be called on finalisation. This is an opportunity for the root (None) not to accumulate properties from its immediate children for example. For depth first finalisation the child class should call finalise on each child first as this function does.

lineNum

The line number of the parent file that included me.

Returns:int – Line number.
class cpip.core.FileIncludeGraph.FileIncludeGraph(theFile, theState, theCondition, theLogic)

Recursive class that holds a graph of include files and and line numbers of the file that included them.

This class builds up a graph (actually a tree) of file includes. The insertion order is significant in that it is expected to be the order experienced by a translation unit processor. addBranch() is the way to add to the data structure.

This class does not distinguish between conditional compilation states that are True or False. Nor does this class evaluate theCondition in any way, it is merely stored for representation.

__init__(theFile, theState, theCondition, theLogic)

Constructor.

This class does not distinguish between conditional compilation states that are True or False. Nor does this class evaluate theCondition in any way, it is merely stored for representation.

Parameters:
  • theFile (str) – A file ID (e.g. a path)
  • theState (bool) – A boolean conditional compilation state.
  • theCondition (str) – A conditional compilation condition string e.g. "a >= b+2".
  • theLogic (list([str]), str) –

    If theLogic is taken from an IncludeHandler as a list of items. e.g. ['<foo.h>, CP=None, sys=None, usr=include/foo.h']

    Each string after item[0] is of the form: key=value

    Where:

    key is a key in self.INCLUDE_ORIGIN_CODES = is the ‘=’ character.

    value is the result, or ‘None’ if not found.

    [0] is the invocation [-1] is the final resolution.

    The intermediate ones are various tries in order. So ['<foo.h>', 'CP=None', 'sys=None', 'usr=include/foo.h'] would mean:

    1. ‘<foo.h>’ the include directive was: #include <foo.h>
    2. ‘CP=None’ the Current place was searched and nothing found.
    3. ‘sys=None’ the system include(s) were searched and nothing found.
    4. ‘usr=include/foo.h’ the user include(s) were searched and include/foo.h was found.
Returns:

NoneType

__weakref__

list of weak references to the object (if defined)

_getBranches(theBrancheS, aBranch)

Recursive call to the tree, adds each unique branch in full.

_retFileLine(theLine)

Returns ‘#d’ appended to the filename.

_retLatestBranch(theList)

Recursive call that returns the branch to the last inserted leaf. theList is modified in-place.

_retLatestBranchDepth(i)

Recursive call that returns an integer that is the depth of the latest branch.

_retString(theIndent)

Returns an indented string recursively.

Parameters:theIndent (int) – Size of indent.
Returns:str – Indented string.
_splitFileLine(theStr)

Splits a file name and line number, the latter is returned as an integer or None if no match.

acceptVisitor(visitor, depth, line)

Hierarchical visitor pattern. This accepts a visitor object and calls visitor.visitGraph(self, depth, line) on that object where depth is the current depth in the graph as an integer and line the line that is a non-monotonic sibling node ordinal.

Parameters:
  • visitor (cpip.core.FileIncludeGraph.FigVisitorFileSet, cpip.core.FileIncludeGraph.FigVisitorTree) – The visitor.
  • depth (int) – Visitor depth.
  • line (int) – File line.
Returns:

NoneType

addBranch(theFileS, theLine, theIncFile, theState, theCondition, theLogic)

Adds a branch to the graph.

Parameters:
  • theFileS (list([str])) – A list of files that form the branch.
  • theLine (int) – An integer value of the line number of the #include statement of the last named file in theFileS.
  • theIncFile (str) – The file that is included.
  • theState (bool) – A boolean that describes the conditional compilation state.
  • theCondition (str) – The conditional compilation test e.g. '1>0'
  • theLogic (list([str])) – A string representing how the branch was obtained.
Returns:

NoneType

Raises:

ExceptionFileIncludeGraph if:

  • The branch is zero length.
  • The branch does not match the existing graph (this function just immediately
    checks the first item on the branch but the others are done recursively).
  • theLine is a duplicate of an existing line.
  • The branch has missing nodes.
condComp

Returns the condition, as a string, under which this file was included e.g. "(a > b) && (1 > 0)".

Returns:str – The evaluated conditional compilation string.
condCompState

Returns the recorded conditional compilation state as a boolean.

Returns:bool – The state.
dumpGraph(theS=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, theI='')

Writes out the graph to a stream.

fileName

Returns the current file name.

Returns:str – The file name.
findLogic

Returns the findLogic string passed in in the constructor.

Returns:list([str]),str – The logic string.
genChildNodes()

Yields each child node as a FileIncludeGraph object.

numTokens

The total number of tokens seen by the PpLexer. Returns None if not initialised. Note: This is the number of tokens for this file only, it does not include the tokens that this file might include.

Returns:int – Count of tokens.
numTokensIncChildren

The total number of tokens seen by the PpLexer including tokens from files included by this one. Returns None if not initialised.

May raise ExceptionFileIncludeGraphTokenCounter is the token counters have been loaded inconsistently (i.e. the children have not been loaded).

Returns:int – Count of tokens.
numTokensSig

The number of significant tokens seen by the PpLexer. A significant token is a non-whitespace, non-conditionally compiled token. Returns None if not initialised.

Note

This is the number of tokens for this file only, it does not include the tokens that this file might include.

Returns:int – Count of tokens.
numTokensSigIncChildren

The number of significant tokens seen by the PpLexer including tokens from files included by this one. A significant token is a non-whitespace, non-conditionally compiled token. Returns None if not initialised.

May raise ExceptionFileIncludeGraphTokenCounter is the token counters have been loaded inconsistently (i.e. the children have not been loaded).

Returns:int – Count of tokens.
retBranches()

Returns a list of lists of the branches with ‘#’ then the line number.

retLatestBranch()

Returns the branch to the last inserted leaf as a list of branch strings.

retLatestBranchDepth()

Walks the graph and returns an integer that is the depth of the latest branch.

retLatestBranchPairs()

Returns the branch to the last inserted leaf as a list of pairs (filename, integer_line).

retLatestLeaf()

Returns the last inserted leaf, a FileIncludeGraph object.

retLatestNode(theBranch)

Returns the last inserted node, a FileIncludeGraph object on the supplied branch.

This is generally used during dynamic construction by a caller that understands the state of the file include branch.

Parameters:theBranch (list([str])) – Branch.
Returns:cpip.core.FileIncludeGraph.FileIncludeGraph – The include graph.
setTokenCounter(theTokCounter)

Sets the token counter for this node which is a PpTokenCount object. The PpLexer sets this as the token count for this file only. This files #include‘s are a separate token counter.

Parameters:theTokCounter (cpip.core.PpTokenCount.PpTokenCount) – Token counter.
Returns:NoneType
tokenCounter

Gets the token counter for this node, a PpTokenCount object.

Returns:cpip.core.PpTokenCount.PpTokenCount – The counter object.
class cpip.core.FileIncludeGraph.FileIncludeGraphRoot

Root class of the file include graph. This is used when there is a virtual or dummy root. It contains a list of FileIncludeGraph objects. In this way it can represent the list of graphs that would result from a list of pre-includes followed by the ITU itself.

In practice this is used by the PpLexer for this purpose where the dummy root is represented by None.

__init__()

Constructor.

__weakref__

list of weak references to the object (if defined)

acceptVisitor(visitor)

Hierarchical visitor pattern. This accepts a visitor object and calls visitor.visitGraph(self, depth, line) on that object where depth is the current depth in the graph as an integer and line the line that is a non-monotonic sibling node ordinal.

Parameters:visitor (cpip.core.FileIncludeGraph.FigVisitorFileSet, cpip.core.FileIncludeGraph.FigVisitorTree) – The visitor
Returns:NoneType
addGraph(theGraph)

Add a FileIncludeGraph object.

Parameters:theGraph (cpip.core.FileIncludeGraph.FileIncludeGraph) – The graph.
Returns:NoneType
dumpGraph(theS=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)

Dump the node for debug/trace.

graph

The latest FileIncludeGraph object I have. Will raise a ExceptionFileIncludeGraphRoot if nothing there.

Returns:cpip.core.FileIncludeGraph.FileIncludeGraph – The graph.
numTrees()

Returns the number of FileIncludeGraph objects.

Returns:int – Number of trees.