A SourceReader allows you to read input from some source, either one single document of
content or several named or indexed source documents, in such a way that each character read
registers its position in the source as a tuple index-line-column.
That is, the main problem it solves is that of calculating the position of each character read
by taking into account characters indicating the end-of-line.
It also solves the problem of input divided among several documents, as it is usually the case
with source code, and it provides a couple of additional features:
to use some parts of the input as extra annotations by marking them as non visible, so the
input can be read as if the annotations were not there, and
to allow the relationship of parts of the input with identifiers naming "regions", thus
making it possible for external tools to identify those parts with ease.
takeWhile, reading some characters from the current document
based on a condition, and
beginRegion and
endRegion, manipulating "regions".
When reading from sources with multiple documents of input, skipping moves inside a document
until there are no more characters, then an end of document position is reached (a special
position just after the last character of that document), and then a new document is started.
Regions are reset at the beginning of each document.
When the last document has been processed, and the last end of document has been skipped, the
end of input is reached (a special position just after all the documents).
A SourceReader also has a special position,
UnknownPosition, as a static member of the class,
indicating that the position is not known.
A source position may be known (pointing to a particular position into a
SourceReader) or unknown (if a position cannot be determined).
The boolean property isUnknown
indicates which is the case.
Additionally, a string representation of any SourcePosition
can be obtained through toString
for internal use purposes.
A typical use of SourcePositions is relating nodes of an AST
representation of code to particular positions in the string version of the
source code (that may come from several input documents).
A SourceReader allows you to read input from some source, either one single document of content or several named or indexed source documents, in such a way that each character read registers its position in the source as a tuple index-line-column. That is, the main problem it solves is that of calculating the position of each character read by taking into account characters indicating the end-of-line. It also solves the problem of input divided among several documents, as it is usually the case with source code, and it provides a couple of additional features:
A SourceReader is created using a SourceInput and then SourcePositions, in particular SourceReader/SourcePositions.AbstractKnownSourcePositions, can be read from it. Possible interactions with a SourceReader includes:
A SourceReader also has a special position, UnknownPosition, as a static member of the class, indicating that the position is not known.
See SourceReader documentation for more details.
Source positions
SourcePositions point to particular positions in the source given by a SourceReader. All SourcePositions are created only through SourceReader.
A source position may be known (pointing to a particular position into a SourceReader) or unknown (if a position cannot be determined). The boolean property isUnknown indicates which is the case.
Additionally, a string representation of any SourcePosition can be obtained through toString for internal use purposes.
A typical use of SourcePositions is relating nodes of an AST representation of code to particular positions in the string version of the source code (that may come from several input documents).
Author
Alan Rodas Bonjour alanrodas@gmail.com