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: - theFigNode (
cpip.core.FileIncludeGraph.FileIncludeGraph
) – AFileIncludeGraph
as a graph node. - theDepth (
int
) – The current depth in the graph as an integer. - theLine (
int
) – The line that is a non-monotonic sibling node ordinal.
Returns: NoneType
- theFigNode (
-
-
class
cpip.core.FileIncludeGraph.
FigVisitorTree
(theNodeClass)¶ This visitor can visit a graph of
FileIncludeGraphRoot
andFileIncludeGraph
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
orFileIncludeGraph
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
- theNode (
-
_addSibling
(theNode, theLine)¶ Add a sibling.
Parameters: - theNode (
cpip.core.FileIncludeGraph.FileIncludeGraph
) – The sibling node. - theLine (
int
) – The line number.
Returns: NoneType
- theNode (
-
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: - theFigNode (
cpip.core.FileIncludeGraph.FileIncludeGraph
) – The node. - depth (
int
) – Node depth. - line (
int
) – Line number.
Returns: NoneType
- theFigNode (
-
-
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:- ‘<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.
- ‘<foo.h>’ the include directive was:
Returns: NoneType
- theFile (
-
__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
- visitor (
-
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: - 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.
- theFileS (
-
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 visitorReturns: 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 aExceptionFileIncludeGraphRoot
if nothing there.Returns: cpip.core.FileIncludeGraph.FileIncludeGraph
– The graph.
-
numTrees
()¶ Returns the number of
FileIncludeGraph
objects.Returns: int
– Number of trees.
-