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:
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.
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.- theLline (
-
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.- theLline (
-
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.