MacroHistoryHtml

Writes out a macro history in HTML.

Macros can be:

  • Active - In scope at the end of processing a translation unit (one per identifier).
  • Inactive - Not in scope at the end of processing a translation unit (>=0 per identifier).

And:

  • Referenced - Have had some influence over the processing of the translation unit.
  • Not Referenced - No influence over the processing of the translation unit.

Example test:

Macros with reference counts of zero are not that interesting so they are relegated to a page (<file>_macros_noref.html) that just describes their definition and where they where defined.

Macros _with_ reference counts are presented on a page (<file>_macros_ref.html) with one section per macro. The section has:

  • Definition
  • Where defined
  • Optionally: This macro depends on the following macros:
  • Optionally: Macros that depend on this macro:

These two HTML pages are joined by a <file>_macros.html this lists (and links to) the identifiers in this order:

  • Active, ref count >0
  • Inactive, ref count >0
  • Active, ref count =0
  • Inactive, ref count =0

Macro HTML IDs

This is identifier + '_' + n. For any active macro the value of n is the number of previously defined macros with the same name. Current code is like this:

myUndefIdxS, isDefined = myMacroMap[aMacroName]
# Write the undefined ones
for anIndex in myUndefIdxS:
    myMacro = theEnv.getUndefMacro(anIndex)
    startLetter = _writeTrMacro(theS, theHtmlPath, myMacro,
                                anIndex, startLetter, retVal)
# Now the defined one
if isDefined:
    myMacro = theEnv.macro(aMacroName)
    startLetter = _writeTrMacro(theS, theHtmlPath, myMacro,
                                len(myUndefIdxS), startLetter, retVal)
cpip.MacroHistoryHtml.TITLE_ANCHOR_LINKTEXT_MACROS_HISTORY = ('Macro Usage (referenced macros only)', 'history', 'usage')

Visible links to macro history.

cpip.MacroHistoryHtml.TITLE_ANCHOR_LINKTEXT_MACROS_IN_SCOPE = ('Macros In Scope', 'Macros_In_Scope', 'usage')

Visible links to macros in scope.

cpip.MacroHistoryHtml.TITLE_ANCHOR_LINKTEXT_MACROS_TABLE = ('Macro Environment (all macros, alphabetical):', 'macro_table', 'Environment')

Visible links to macros.

cpip.MacroHistoryHtml.TITLE_ANCHOR_LINKTEXT_MACROS_TESTED_WHEN_NOT_DEFINED = ('Macros Tested When Not Defined', 'Macros_Never_Def', 'tested')

Visible links to macros tested when not defined.

cpip.MacroHistoryHtml._getMacroDependencyTrees(theMacroAdjList, theMacro)

Returns the dependency trees (parent/child, child/parent) for the macro. Either can be None.

Parameters:
  • theMacroAdjList (:py:class`cpip.util.Tree.DuplexAdjacencyList`) – The adjacency list.
  • theMacro (cpip.core.PpDefine.PpDefine) – The macro.
Returns:

tuple([NoneType, NoneType]),tuple([NoneType, cpip.util.Tree.Tree]),tuple([cpip.util.Tree.Tree, NoneType]) – A pair of parent -> child tree and child -> parent tree.
cpip.MacroHistoryHtml._linkToIndex(theS, theIdx)

Write a link to ‘Return to’ the index page.

Parameters:
Returns:

NoneType
cpip.MacroHistoryHtml._macroHistoryIndexName(theItu)
Parameters:theItu (str) – Ignored.
Returns:str – The HTML file name of the macro history.
cpip.MacroHistoryHtml._macroHistoryNorefName(theItu)
Parameters:theItu (str) – Ignored.
Returns:str – The HTML file name of the macro history with no references.
cpip.MacroHistoryHtml._macroHistoryRefName(theItu)
Parameters:theItu (str) – Ignored.
Returns:str – The HTML file name of the macro history with references.
cpip.MacroHistoryHtml._macroIdTestedWhenNotDefined(theMacroId)
Parameters:theMacroId (str) – The macro ID.
Returns:str – Link ID.
cpip.MacroHistoryHtml._retMacroId(theMacro, theIndex=None)
Parameters:
Returns:

str – Encoded XML string.
cpip.MacroHistoryHtml._retMacroIdHrefNames(theEnv, theItu)

Returns a dict of {identifier : [(fileId, lineNum, href_name), ...], ...} for annotating HTML.

The order in the list is the translation unit order in which macros are defined/undef’d.

Parameters:
Returns:

dict({str : list([tuple([str, int, str])])]}) – Identifier dictionary.
cpip.MacroHistoryHtml._retSetMacros(theEnv, isReferenced, isActive)

Returns a set of {(Identifier, href_name), ...} of macros identifiers and their references. Multiple identifier that have been def’d/undef’d have unique, lexagraphically sequential hrefs (with a trailing integer).

Parameters:
  • theEnv (cpip.core.MacroEnv.MacroEnv) – The macro environment.
  • isReferenced (bool) – If True only macros that are referenced are included.
  • isActive (bool) – Only currently active macros are included, undef’d ones are excluded.
Returns:

set([]),set([tuple([str, str])]) – <insert documentation for return values>
Raises:

StopIteration
cpip.MacroHistoryHtml._tdFilePathCallback(theS, attrs, k, v)

Callback function for the file reference table.

Parameters:
  • theS (cpip.util.XmlWrite.XhtmlStream) – HTML stream.
  • attrs (dict({str : [str]})) – Element attributes.
  • k (list([str])) – Keys.
  • v (list([tuple([str, str])])) – Values.
Returns:

NoneType
cpip.MacroHistoryHtml._writeMacroDefinitionAndAnchor(theS, theDef, theIntOccurence)

Writes a definition of the macro with an anchor that can be linked to. This also writes an anchor based on the first character of the macro name so that alphabetic links can reference it.

Parameters:
Returns:

str – Anchor name.
cpip.MacroHistoryHtml._writeMacroDependencies(theS, theEnv, theMacro, theMacroAdjList, theItu)

Writes out the macro dependencies.

Parameters:
Returns:

NoneType
cpip.MacroHistoryHtml._writeMacroDependenciesTable(theS, theEnv, theAdjList, theItu)

Writes all the macro dependencies to a rowspan/colspan HTML that references something.

table with links to the position in the HTML representation of the file

This uses a particular design pattern that uses a DictTree to sort out the rows and columns. In this case the DictTree values are lists of pairs (href, nav_text) where nav_text is the line_col of the referencing file.

Parameters:
Returns:

NoneType
cpip.MacroHistoryHtml._writeMacroHistory(theS, theMacro, theOmitFiles, theIntOccurence)

Writes out the macro history from a PpDefine object. theMacro - a PpDefine() object. theOmitFiles - a list of pseudo files not to link to e.g. [‘Unnamed Pre-include’,].

Parameters:
  • theS (cpip.util.XmlWrite.XhtmlStream) – The HTML stream.
  • theMacro (cpip.core.PpDefine.PpDefine) – The macro.
  • theOmitFiles (list([str])) – A list of pseudo files not to link to e.g. [‘Unnamed Pre-include’,].
  • theIntOccurence (int) – The occurence of the macro which will be added to the link ID.
Returns:

NoneType
cpip.MacroHistoryHtml._writeMacroReferencesTable(theS, theFlcS)

Writes all the references to a file/line/col in a rowspan/colspan HTML table with links to the position in the HTML representation of the file that references something.

This uses a particular design pattern that uses a DictTree to sort out the rows and columns. In this case the DictTree values are lists of pairs (href, nav_text) where nav_text is the line-col of the referencing file.

Parameters:
  • theS (cpip.util.XmlWrite.XhtmlStream) – HTML stream.
  • theFlcS (list([]), list([cpip.core.FileLocation.FileLineCol([str, int, int])])) – File location.
Returns:

NoneType
cpip.MacroHistoryHtml._writeMacrosTestedButNotDefined(theS, theMacroId, theEnv)

Writes out the macro history for macros tested but not defined.

Parameters:
Returns:

NoneType
cpip.MacroHistoryHtml._writeSectionOnMacroHistory(theS, theEnv, theOmitFiles, theHtmlPath, theItu, isReferenced)

Write the section that says where macros were used with links to the file/line/column.

Parameters:
  • theS (cpip.util.XmlWrite.XhtmlStream) – The HTML stream.
  • theEnv (cpip.core.MacroEnv.MacroEnv) – The macro environment.
  • theOmitFiles (list([str])) – A list of pseudo files not to link to e.g. [‘Unnamed Pre-include’,].
  • theHtmlPath (str) – The path to the HTML file.
  • theItu (str) – Initial Translation Unit (ITU).
  • isReferenced (bool) – True if macro was referenced (used).
Returns:

dict({str : [str]}) – Map of {macro_identifier : file_id_link, ...}`
Raises:

StopIteration
cpip.MacroHistoryHtml._writeTableOfMacros(theS, theEnv, theHtmlPath)

Writes the table of macros, where they are defined, their ref count etc.

cpip.MacroHistoryHtml._writeTd(theStream, theStr)

Write a <td> element and contents.

cpip.MacroHistoryHtml._writeTdMacro(theS, theDef, startLetter, theIntOccurence)

Write the macro cell in the general table. theDef is a PpDefine object.

cpip.MacroHistoryHtml._writeTh(theStream, theStr)

Write a <th> element and contents.

cpip.MacroHistoryHtml._writeTocMacros(theS, theEnv, isReferenced, filePrefix)

Write out the table of contents from the environment. isReferenced controls whether these are referenced macros (interesting) or non referenced macros (a larger, less interesting set). filePrefix - If not None this is the HTML file to link to.

Parameters:
Returns:

NoneType
cpip.MacroHistoryHtml._writeTrMacro(theS, theHtmlPath, theMacro, theIntOccurence, theStartLetter, retMap)

Write the macro as a row in the general table. theMacro is a PpDefine object. theStartLetter is the current letter we are writing [‘A’, ‘B’, ...] which writes an anchor at the beginning of each letter section.

cpip.MacroHistoryHtml.processMacroHistoryToHtml(theLex, theHtmlPath, theItu, theIndexPath)

Write out the macro history from the PpLexer as HTML. Returns a map of: {identifier : [(fileId, lineNum, href_name), ...], ...} which can be used by src->html generator for providing links to macro pages.

Parameters:
  • theLex (cpip.core.PpLexer.PpLexer) – The lexer.
  • theHtmlPath (str) – File path to write to.
  • theItu (str) – Path to the initial translation unit (ITU).
  • theIndexPath (str) – Path to the index.
Returns:

tuple([dict({str : [list([tuple([<class 'str'>, <class 'int'>, str])]), list([tuple([<class 'str'>, int, str])]), list([tuple([str, int, str])])]}), str]) – Map that links macro names ot file positions.
cpip.MacroHistoryHtml.splitLine(theStr, splitLen=60, splitLenHard=80)

Splits a long string into string that is a set of lines with continuation characters.

Parameters:
  • theStr (str) – Long line.
  • splitLen (int) – Soft split length.
  • splitLenHard (int) – Hard split length.
Returns:

str – Line with continuation character and newlines.
cpip.MacroHistoryHtml.splitLineToList(sIn, splitLen=60, splitLenHard=80)

Splits a long string into a list of lines. This tries to do it nicely at whitespaces but will force a split if necessary.

Parameters:
  • sIn (str) – Line to split.
  • splitLen (int) – Soft split length.
  • splitLenHard (int) – Hard split length.
Returns:

list([str]) – List of lines.