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 = {'comp': 'Compiler specific directories', 'TU': 'Translation unit', 'sys': 'System include directories', None: 'Not found', 'usr': 'User include directories', 'CP': 'Current Place'}

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:

1. key is a key in self.INCLUDE_ORIGIN_CODES
2. = is the '=' character.
3. value is the result, or ‘None’ if not found.
4. Item [0] is the invocation
5. 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.

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

If not None return value this also records the CP for the file.

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

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