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.

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, ...}.

fileNameSet¶: The set of file names seen.

visitGraph(theFigNode, theDepth, theLine)¶

Hierarchical visitor pattern.

theFigNode: A FileIncludeGraph as a graph node.
theDepth: The current depth in the graph as an integer.
theLine: The line that is a non-monotonic sibling node ordinal.

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.

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

tree()¶: Returns the top level node object as the only copy. This also finalises the tree.

visitGraph(theFigNode, depth, line)¶: Visit the give node.

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.

addChild(theObj)¶: Add the object as a child.

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.

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.

theFile - a file ID (e.g. a path)

theState - a boolean conditional compilation state.

theCondition - a conditional compilation condition string e.g. “a >= b+2”.

thelogic - a string explanation of how that the file was found.

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:

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

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.

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.

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

Adds a branch to the graph.

theFileS is a list of files that form the branch.

theLine is an integer value of the line number of the #include statement of the last named file in theFileS.

theIncFile is the file that is included.

theState is a boolean that describes the conditional compilation state.

theCondition is the conditional compilation test e.g. ‘1>0’

theLogic is a string representing how the branch was obtained.

May raise 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)".

condCompState¶: Returns the recorded conditional compilation state as a boolean.

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.

findLogic¶: Returns the findLogic string passed in in the constructor.

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.

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).

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.

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).

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.

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 #includes are a separate token counter.

tokenCounter¶: Gets the token counter for this node, a PpTokenCount 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.

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.

addGraph(theGraph)¶: Add a FileIncludeGraph object.

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.

numTrees()¶: Returns the number of FileIncludeGraph objects.