IncludeHandler¶
Provides handlers for #including files.
-
class
cpip.core.IncludeHandler.
CppIncludeStd
(theUsrDirs, theSysDirs)¶ Class that applies search rules for #include statements.
Search tactics based on RVCT and Berkeley UNIX search rules:
I is the usr includes. J is the sys includes. Size of I Size of J #include <...> #include "..." 0 0 None CP 0 >0 SYSTEMINCLUDEdirs CP, SYSTEMINCLUDEdirs >0 0 USERINCLUDEdirs CP, USERINCLUDEdirs >0 >0 SYSTEMINCLUDEdirs, CP, USERINCLUDEdirs, USERINCLUDEdirs SYSTEMINCLUDEdirs
ISO/IEC 9899:1999 (E) 6.10.2-3 means that a failure of q-char must be retried as if it was a h-char. i.e. A failure of a q-char-sequence thus:
#include "..."
Is to be retried as if it was written as a h-char-sequence thus:
#include <...>
See: _includeQcharseq()
-
INCLUDE_ORIGIN_CODES
= {'sys': 'System include directories', 'usr': 'User include directories', 'comp': 'Compiler specific directories', 'TU': 'Translation unit', 'CP': 'Current Place', None: 'Not found'}¶ Codes for the results of a search for an include
-
canInclude
()¶ Returns True if the last include succeeded.
-
clearFindLogic
()¶ Clears the list of find results for a single #include statement.
-
clearHistory
()¶ Clears the CP stack. This needed if you use this class as a persistent one and it encounters an exception. You need to call this function before you can reuse it.
-
cpStack
¶ Returns the current stack of current places.
-
cpStackPop
()¶ Pops and returns the CP string off the current place stack. This is public so that the PpLexer can use it when processing pre-include files that might themselves include other files.
-
cpStackPush
(theFpo)¶ Appends the CP from the FilePathOrigin to the current place stack. This is public so that the PpLexer can use it when processing pre-include files that might themselves include other files.
-
cpStackSize
¶ Returns the size of the current stack of current places.
-
currentPlace
¶ Returns the last current place or None if #include failed.
-
endInclude
()¶ Notify end of #include’d file. This pops the CP stack.
-
finalise
()¶ Finalise at the end of the translation unit. Might raise a ExceptionCppInclude.
-
findLogic
¶ Returns a list of strings that describe _how_ the file was found For example:
['<foo.h>', 'CP=None', 'sys=None', 'usr=include/foo.h']
Each string after [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.
- Item [0] is the invocation
- Item [-1] is the final resolution.
The intermediate ones are various tries in order. So:
['<foo.h>', 'CP=None', 'sys=None', 'usr=include/foo.h']
Wwould mean:
- [0]:
'<foo.h>'
the include directive was:#include <foo.h>
- [1]:
'CP=None'
the Current place was searched and nothing found. - [2]:
'sys=None'
the system include(s) were searched and nothing found. - [3]:
'usr=include/foo.h'
the user include(s) were searched and include/foo.h was found.
- key is a key in
-
includeHeaderName
(theStr)¶ Return the file location of a #include header-name where the header-name is a pp-token either a <h-char-sequence> or a “q-char-sequence” (including delimiters). If not None return value this also records the CP for the file.
-
includeNextHeaderName
(theStr)¶ Return the file location of a #include_next header-name where the header-name is a pp-token either a <h-char-sequence> or a “q-char-sequence” (including delimiters).
This is a GCC extension, see: https://gcc.gnu.org/onlinedocs/cpp/Wrapper-Headers.html
This never records the CP for the found file (if any).
-
initialTu
(theTuIdentifier)¶ Given an Translation Unit Identifier this should return a class FilePathOrigin or None for the initial translation unit. As a precaution this should include code to check that the stack of current places is empty. For example:
if len(self._cpStack) != 0: raise ExceptionCppInclude('setTu() with CP stack: %s' % self._cpStack)
-
validateCpStack
()¶ Tests the coherence of the CP stack. A None can not be followed by a non-None.
-
-
class
cpip.core.IncludeHandler.
CppIncludeStdOs
(theUsrDirs, theSysDirs)¶ This implements _searchFile() based on an OS file system call.
-
initialTu
(theTuPath)¶ Given an path as a string this returns the class FilePathOrigin or None for the initial translation unit
-
-
class
cpip.core.IncludeHandler.
CppIncludeStdin
(theUsrDirs, theSysDirs)¶ This reads stdin for the ITU but delegates _searchFile() to the OS file system call.
-
initialTu
(theTuPath)¶ Given an path as a string this returns the class FilePathOrigin or None for the initial translation unit
-
-
class
cpip.core.IncludeHandler.
CppIncludeStringIO
(theUsrDirs, theSysDirs, theInitialTuContent, theFilePathToContent)¶ This implements _searchFile() based on a lookup of stings that returns StringIO file-like object.
-
initialTu
(theTuIdentifier)¶ Given an path as a string this returns the class FilePathOrigin or None for the initial translation unit
-
-
exception
cpip.core.IncludeHandler.
ExceptionCppInclude
¶ Simple specialisation of an exception class for the CppInclude.
-
class
cpip.core.IncludeHandler.
FilePathOrigin
(fileObj, filePath, currentPlace, origin)¶ FilePathOrigin is a class used externally to collect:
- An open file object that can be read by the caller.
- The file path of that object, wherever found.
- The ‘current place’ of that file, wherever found. This will affect subsequent calls.
- The origin code, i.e. how it was found.
Any or all or these attributes may be None as the methods
_searchFile()
,_includeQcharseq()
and_includeHcharseq()
return such an object (or None).-
currentPlace
¶ Alias for field number 2
-
fileObj
¶ Alias for field number 0
-
filePath
¶ Alias for field number 1
-
origin
¶ Alias for field number 3