FileLocation¶

Various classes for use by the preprocessor for keeping track of the location in a set of files.

This consists of three related classes:

LogicalPhysicalLineMap:

This low-level class maintains and internal theoretical relationship between the logical position in a string and the physical position. These differ when physical characters are replaced by logical ones.

This is not usually used directly by other modules.

FileLocation:

This consists of a stack of one or more LogicalPhysicalLineMap objects each of which represents a phase of translation. This understands what it means to replace a trigraph or encounter a line continuation phrase.

Typically this is used by a cpip.core.PpTokensiser.PpTokeniser.

CppFileLocation:

This consists of a stack of one or more FileLocation objects each of which represents an ITU or included file. Conceptually this is a table of columns (each a FileLocation object) and cells (each a LogicalPhysicalLineMap). The public API gives access to the ‘current’ LogicalPhysicalLineMap i.e. the top right one in the table. The public API allows pushing (adding a column when a file is #include’d) and popping (removing the last column at the end of #include processing).

Typically this is used by a cpip.core.PpLexer.PpLexer.

Using line continuation in LogicalPhysicalLineMap:

class FileLocation needs to poke the underlying LogicalPhysicalLineMap in the right way...

This is accomplished by calling from class FileLocation the underlying LogicalPhysicalLineMap._addToIr()

This makes calls occur in N pairs.

N = The number of ‘n’ phrases.

L(n) is the length of the physical line n (0 <= n < N) not including the ‘n’

Make N calls to _addIr(...)

NOTE: The use of 1+ and -1* here _addToIr(theLogicalLine=a, theLogicalCol=1+b, dLine=c, dColumn=-1*d)

Where:

a(n) = The current logical line number (starting at 1), constant for the group
b(n) = Sigma[L(n) for 0...n)]
c(n) = 1
d(n) = L(n)

Examples:

myPstrS = ['abc\n', '\n', 'd\n', 'ef\n',]
N = 3
L(n) -> (3, 0, 1)
a = 1, c = 1
(b, d)
(3, 3)
(3, 0)
(4, 1)

myPstrS = ['abc\n', 'd\n', '\n', 'ef\n',]
N = 3
L(n) -> (3, 1, 0)
a = 1, c = 1
(b, d)
(3, 3)
(4, 1)
(4, 0)

myPstrS = ['ab\n', 'c\n', 'd\n', 'ef\n',]
N = 3
L(n) -> (2, 1, 1)
a = 1, c = 1
(b, d)
(2, 2)
(3, 1)
(4, 1)

The second call of the pair is as follows, this needs to know N so has to be done after all first-of-pair calls:

_addToIr(theLogicalLine=d, theLogicalCol=1, dLine=e, dColumn=f)

Where:

d = n+2 where n is the number of the '\n' in the group starting at 0
e = N-n-1 where N is the total number of '\n' in the group.
f = Length of the last physical line spliced, not including the '\n'

Programatically:

for n in range(N):
    myLplm._addToIr(theLogicalLine=n+2, theLogicalCol=1, dLine=N-n-1, dColumn=f)

In all the examples above f = 2

exception cpip.core.FileLocation.ExceptionFileLocation¶: Simple specialisation of an exception class for the FileLocation classes.

class cpip.core.FileLocation.FileLine(fileId, lineNum)¶

Simple PODs for file location for anyone that wants to use them

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

static __new__(_cls, fileId, lineNum)¶: Create new instance of FileLine(fileId, lineNum)

__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 FileLine object from a sequence or iterable

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

fileId¶: Alias for field number 0

lineNum¶: Alias for field number 1

class cpip.core.FileLocation.FileLineCol(fileId, lineNum, colNum)¶

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

static __new__(_cls, fileId, lineNum, colNum)¶: Create new instance of FileLineCol(fileId, lineNum, colNum)

__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 FileLineCol object from a sequence or iterable

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

colNum¶: Alias for field number 2

fileId¶: Alias for field number 0

lineNum¶: Alias for field number 1

class cpip.core.FileLocation.FileLocation(theFileName)¶

Class that persists the line/column location in a source file. This also handles various passes of the same file for the PpTokeniser.

__init__(theFileName)¶

Initialise with a file name (actually an ID)

NOTE: We do not check for it’s existence as we are not allied to the file system (we could get the files from a database instead.

Parameters:	theFileName (`NoneType, str`) – File ID for example the file path.
Returns:	`NoneType`

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

colNum¶

Returns:	`int` – Column number.

fileLineCol()¶

Return an instance of FileLineCol from the current settings.

Returns:	`cpip.core.FileLocation.FileLineCol([str, int, int])` – File location.

fileName¶

Returns:	`str` – <insert documentation for return values>

incCol(num=1)¶

Increment the column by num. There is no range check on num.

Parameters:	num (`int`) – Amount to increment, default 1.
Returns:	`NoneType`

incLine(num=1)¶

Increment the line by num. There is no range check on num.

Parameters:	num (`int`) – Amount to increment, default 1.
Returns:	`NoneType`

lineCol¶: Returns the current line and column number as a pair.

lineNum¶

Returns:	`int` – Line number.

lineSpliceCount¶: The number of line splices in the current splice group.

logicalPhysicalLineMap¶: Return the current top level LogicalPhysicalLineMap Read Only instance.

logicalToPhysical(theLline, theLcol)¶

Returns the physical line and column number for a logical line and column.

Parameters:	theLline (`int`) – Logical line number. theLcol (`int`) – Logical column number.
Returns:	`tuple([int, int])` – Physical line and column.

pLineCol¶

Returns the current physical line and column number.

Returns:	`tuple([int, int])` – Location.

pformatLogicalToPhysical(theLfile, thePfile)¶: Given a logical and a physical representation this goes through character by both character, pretty formats the comparison and returns the formatted string.

retColNum()¶

Returns:	`int` – Column number.

retLineNum()¶

Returns:	`int` – Line number.

retPredefinedMacro(theName)¶: Returns the value of __FILE__ or __LINE__. Applies ISO/IEC 14882:1998(E) 16 Predefined macro names [cpp.predefined] note 2 May raise ExceptionFileLocation if theName is something else.

setTrigraph()¶: Records that a trigraph has be substituted at the current place.

spliceLine(thePhysicalLine)¶: Update the line/column mapping to record a line splice.

startNewPhase()¶

Starts a new processing phase e.g. a translation phase. This adds a new LogicalPhysicalLineMap() to the stack.

Returns:	`NoneType`

substString(lenPhysical, lenLogical)¶: Records a string substitution at the current logical location. This does NOT update the current line or column, use update(...) to do that.

update(theString)¶

Increment line and column counters from a string.

Parameters:	theString (`str`) – Source code.
Returns:	`NoneType`

class cpip.core.FileLocation.LogicalPhysicalLineMap¶

Class that can map logical positions (i.e. after text substitution) back to the original physical line columns. The effect of various substitutions is as follows:

Phase 1: Trigraph replacement - logical is same or smaller than physical. Phase 1: Mapping non lex.charset to universal-character-name - logical is larger than physical. Phase 2: Line splicing - if done logical is smaller that physical. Phase 3: Digraph replacement - logical is same or smaller that physical.

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

_addToIr(theLogicalLine, theLogicalCol, dLine, dColumn)¶: Adds, or updates a record to the internal representation.

offsetAbsolute(theLineCol)¶: Given a pair of integers that represent line/column starting at zero this returns a tuple pair of the absolute line/column.

offsetRelative(theLineCol)¶: Given a pair of integers that represent line/column starting at START_LINE, START_COLUMN this returns a tuple pair of the relative line/column i.e. starting at (0, 0).

pLineCol(lLine, lCol)¶

Returns the (physical line number, physical column number) from a logical line and logical column.

Parameters:	theLline (`int`) – Logical line number. theLcol (`int`) – Logical column number.
Returns:	`tuple([int, int])` – Physical line and column.

substString(theLogicalLine, theLogicalCol, lenPhysical, lenLogical)¶: Records a string substitution.

cpip.core.FileLocation.START_LINE = 1¶: See ISO/IEC 14882:1998(E) 16.4 Line control [cpp.line] note 2 Means that lines start at 1. We also take the first column to be number 1.