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 = {None: 'Not found', 'sys': 'System include directories', 'usr': 'User include directories', 'comp': 'Compiler specific directories', 'TU': 'Translation unit', 'CP': 'Current Place'}¶: Codes for the results of a search for an include

__init__(theUsrDirs, theSysDirs)¶

Constructor.

Parameters:	theUsrDirs (`list([str])`) – List of search directories for user includes. theSysDirs (`list([str])`) – List of search directories for system includes.
Returns:	`NoneType`

__weakref__¶: list of weak references to the object (if defined)

_currentPlaceFromFile(theFilePath)¶

Helper method that returns the enclosing directory of the file as the current place.

Parameters:	theFilePath (`str`) – File path.
Returns:	`str` – Directory path.

_fixDirsep(theCharSeq)¶

Returns a character sequence with the allowable directory seperator replaced by that the OS will recognise.

Parameters:	theCharSeq (`str`) – The character sequence.
Returns:	`str` – OS compatible character sequence.

_includeHcharseq(theHstr, include_next=False)¶

Return the file location of a #include <...> as a FilePathOrigin object or None on failure.

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

Parameters:	theHstr (`str`) – The include string. include_next (`bool`) – Use GGC extension `#include-next`.
Returns:	`cpip.core.IncludeHandler.FilePathOrigin([_io.TextIOWrapper, str, str, str])` – File path of the included file.

_includeQcharseq(theQstr, include_next=False)¶

Return the file location of a #include "..." as a FilePathOrigin object or None on failure.

If not None return value this also records the ‘current place’ (CP) for the file.

Parameters:	theQstr (`str`) – The include string. include_next (`bool`) – Use GGC extension `#include-next`.
Returns:	`cpip.core.IncludeHandler.FilePathOrigin([_io.TextIOWrapper, str, str, str])` – File path of the included file.

_searchFile(theCharSeq, theSearchPath)¶: Given an HcharSeq/Qcharseq and a searchpath this should return a class FilePathOrigin or None

canInclude()¶

Returns True if the last include succeeded.

Returns:	`bool` – 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.

Returns:	`NoneType`

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.

Parameters:	theFpo (`cpip.core.IncludeHandler.FilePathOrigin([_io.StringIO, str, NoneType, str]), cpip.core.IncludeHandler.FilePathOrigin([_io.TextIOWrapper, str, str, str])`) – The FilePathOrigin to push onto the include stack.
Returns:	`NoneType`

cpStackSize¶

Returns the size of the current stack of current places.

Returns:	`int` – Stack size.

currentPlace¶: Returns the last current place or None if #include failed.

endInclude()¶

Notify end of #include’d file. This pops the CP stack.

Returns:	`NoneType`

finalise()¶

Finalise at the end of the translation unit. Might raise a ExceptionCppInclude.

Returns:	`NoneType`

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']

Item [0] is the invocation. 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 [-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:

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

Returns:	`list([]),list([str])` – How the file was found.

includeHeaderName(theStr)¶

Return the file location of a #include header-name where the header-name is a pp-token (a cpip.core.PpToken.PpToken) with the contents either a <h-char-sequence> or a "q-char-sequence" (including delimiters).

If not None return value this also records the ‘current place’ (CP) for the file.

Parameters:	theStr (`str`) – Header name with delimiters.
Returns:	`cpip.core.IncludeHandler.FilePathOrigin([_io.TextIOWrapper, str, str, str])` – File path of the included 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.

Returns:	`bool` – False on failure.

class cpip.core.IncludeHandler.CppIncludeStdOs(theUsrDirs, theSysDirs)¶

This implements _searchFile() based on an OS file system call.

_searchFile(theCharSeq, theSearchPath)¶

Given an HcharSeq/Qcharseq and a searchpath this tries the file system for the file and returns a FilePathOrigin object or None on failure.

Parameters:	theCharSeq (`str`) – Character sequence. theSearchPath (`str`) – Search path.
Returns:	`NoneType,cpip.core.IncludeHandler.FilePathOrigin([_io.TextIOWrapper, str, str, NoneType])` – File found or `None`.
Raises:	`FileNotFoundError`

initialTu(theTuPath)¶

Given an path as a string this returns the class FilePathOrigin or None for the initial translation unit.

Parameters:	theTuPath (`str`) – File path.
Returns:	`cpip.core.IncludeHandler.FilePathOrigin([_io.TextIOWrapper, str, str, str])` – The file path origin.

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.

__init__(theUsrDirs, theSysDirs, theInitialTuContent, theFilePathToContent)¶: Acts like a IncludeHandler but looks up in theFilePathToContent map that is a {path_string : content_string, ...}. This will be used to simulate resolving a #include statement.

_searchFile(theCharSeq, theSearchPath)¶: Given an HcharSeq/Qcharseq and a searchpath this tries the file system for the file.

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

__getnewargs__()¶: Return self as a plain tuple. Used by copy and pickle.

static __new__(_cls, fileObj, filePath, currentPlace, origin)¶: Create new instance of FilePathOrigin(fileObj, filePath, currentPlace, origin)

__repr__()¶: Return a nicely formatted representation string

_asdict()¶: Return a new OrderedDict which maps field names to their values.

classmethod _make(iterable, new=<built-in method __new__ of type object at 0xa385c0>, len=<built-in function len>)¶: Make a new FilePathOrigin object from a sequence or iterable

_replace(_self, **kwds)¶: Return a new FilePathOrigin object replacing specified fields with new values

currentPlace¶: Alias for field number 2

fileObj¶: Alias for field number 0

filePath¶: Alias for field number 1

origin¶: Alias for field number 3