Package com.oracle.truffle.api.source
Class Source
java.lang.Object
com.oracle.truffle.api.source.Source
Representation of a guest language source code unit and its contents. Sources originate in
several ways:
- Literal: A named text string. These are not indexed and should be considered
value objects; equality is defined based on contents.
SeefromText(CharSequence, String)
- File: Each file is represented as a canonical object, indexed by the
absolute, canonical path name of the file. File contents are read lazily and contents
optionally cached.
SeefromFileName(String)
SeefromFileName(String, boolean)
- URL: Each URL source is represented as a canonical object, indexed by the
URL. Contents are read eagerly and cached.
SeefromURL(URL, String)
- Reader: Contents are read eagerly and treated as a Literal
.
SeefromReader(Reader, String)
- Pseudo File: A literal text string that can be retrieved by name as if it
were a file, unlike literal sources; useful for testing.
SeeasPseudoFile(CharSequence, String)
File cache:
- File content caching is optional, off by default.
- The first access to source file contents will result in the contents being read, and (if enabled) cached.
- If file contents have been cached, access to contents via
getInputStream()
orgetReader()
will be provided from the cache. - Any access to file contents via the cache will result in a timestamp check and possible cache reload.
-
Method Summary
Modifier and TypeMethodDescriptionstatic Source
asPseudoFile
(CharSequence chars, String pseudoFileName) Creates a source from literal text, but which acts as a file and can be retrieved by name (unlike other literal sources); intended for testing.protected void
checkRange
(int charIndex, int length) final LineLocation
createLineLocation
(int lineNumber) Creates a representation of a line number in this source, suitable for use as a hash table key with equality defined to mean equivalent location.final SourceSection
createSection
(String identifier, int lineNumber) Creates a representation of a line of text in the source identified only by line number, from which the character information will be computed.final SourceSection
createSection
(String identifier, int charIndex, int length) Creates a representation of a contiguous region of text in the source.final SourceSection
createSection
(String identifier, int startLine, int startColumn, int length) Creates a representation of a contiguous region of text in the source.final SourceSection
createSection
(String identifier, int startLine, int startColumn, int charIndex, int length) Creates a representation of a contiguous region of text in the source.protected com.oracle.truffle.api.source.Source.TextMap
static Source
fromBytes
(byte[] bytes, int byteIndex, int length, String description, BytesDecoder decoder) Creates a source from raw bytes.static Source
fromBytes
(byte[] bytes, String description, BytesDecoder decoder) Creates a source from raw bytes.static Source
fromFileName
(String fileName) Gets the canonical representation of a source file, whose contents will be read lazily and then cached.static Source
fromFileName
(String fileName, boolean reset) Gets the canonical representation of a source file, whose contents will be read lazily and then cached.static Source
fromReader
(Reader reader, String description) Creates a source whose contents will be read immediately and cached.static Source
fromText
(CharSequence chars, String description) Creates a non-canonical source from literal text.static Source
Creates a source whose contents will be read immediately from a URL and cached.abstract String
getCode()
Return the complete text of the code.final String
getCode
(int lineNumber) Gets the text (not including a possible terminating newline) in a (1-based) numbered line.getCode
(int charIndex, int charLength) final int
getColumnNumber
(int offset) Given a 0-based character offset, return the 1-based number of the column at the position.final InputStream
Access to the source contents.final int
The number of text lines in the source, including empty lines; characters at the end of the source without a terminating newline count as a line.final int
getLineLength
(int lineNumber) The number of characters (not counting a possible terminating newline) in a (1-based) numbered line.final int
getLineNumber
(int offset) Given a 0-based character offset, return the 1-based number of the line that includes the position.final int
getLineStartOffset
(int lineNumber) Given a 1-based line number, return the 0-based offset of the first character in the line.abstract String
getName()
Returns the name of this resource holding a guest language program.abstract String
getPath()
The normalized, canonical name if the source is a file.abstract Reader
Access to the source contents.abstract String
Returns a short version of the name of the resource holding a guest language program (as described in @getName).abstract URL
getURL()
The URL if the source is retrieved via URL.protected abstract void
reset()
static void
setFileCaching
(boolean enabled) Enables/disables caching of file contents, disabled by default.
-
Method Details
-
fromFileName
Gets the canonical representation of a source file, whose contents will be read lazily and then cached.- Parameters:
fileName
- namereset
- forces any existingSource
cache to be cleared, forcing a re-read- Returns:
- canonical representation of the file's contents.
- Throws:
IOException
- if the file can not be read
-
fromFileName
Gets the canonical representation of a source file, whose contents will be read lazily and then cached.- Parameters:
fileName
- name- Returns:
- canonical representation of the file's contents.
- Throws:
IOException
- if the file can not be read
-
fromText
Creates a non-canonical source from literal text. If an already created literal source must be retrievable by name, useasPseudoFile(CharSequence, String)
.- Parameters:
chars
- textual source codedescription
- a note about the origin, for error messages and debugging- Returns:
- a newly created, non-indexed source representation
-
fromURL
Creates a source whose contents will be read immediately from a URL and cached.- Parameters:
url
-description
- identifies the origin, possibly useful for debugging- Returns:
- a newly created, non-indexed source representation
- Throws:
IOException
- if reading fails
-
fromReader
Creates a source whose contents will be read immediately and cached.- Parameters:
reader
-description
- a note about the origin, possibly useful for debugging- Returns:
- a newly created, non-indexed source representation
- Throws:
IOException
- if reading fails
-
fromBytes
Creates a source from raw bytes. This can be used if the encoding of strings in your language is not compatible with Java strings, or if your parser returns byte indices instead of character indices. The returned source is then indexed by byte, not by character.- Parameters:
bytes
- the raw bytes of the sourcedescription
- a note about the origin, possibly useful for debuggingdecoder
- how to decode the bytes into Java strings- Returns:
- a newly created, non-indexed source representation
-
fromBytes
public static Source fromBytes(byte[] bytes, int byteIndex, int length, String description, BytesDecoder decoder) Creates a source from raw bytes. This can be used if the encoding of strings in your language is not compatible with Java strings, or if your parser returns byte indices instead of character indices. The returned source is then indexed by byte, not by character. Offsets are relative to byteIndex.- Parameters:
bytes
- the raw bytes of the sourcebyteIndex
- where the string starts in the byte arraylength
- the length of the string in the byte arraydescription
- a note about the origin, possibly useful for debuggingdecoder
- how to decode the bytes into Java strings- Returns:
- a newly created, non-indexed source representation
-
asPseudoFile
Creates a source from literal text, but which acts as a file and can be retrieved by name (unlike other literal sources); intended for testing.- Parameters:
chars
- textual source codepseudoFileName
- string to use for indexing/lookup- Returns:
- a newly created, source representation, canonical with respect to its name
-
setFileCaching
public static void setFileCaching(boolean enabled) Enables/disables caching of file contents, disabled by default. Caching of sources created from literal text or readers is always enabled. -
reset
protected abstract void reset() -
getName
Returns the name of this resource holding a guest language program. An example would be the name of a guest language source code file.- Returns:
- the name of the guest language program
-
getShortName
Returns a short version of the name of the resource holding a guest language program (as described in @getName). For example, this could be just the name of the file, rather than a full path.- Returns:
- the short name of the guest language program
-
getPath
The normalized, canonical name if the source is a file. -
getURL
The URL if the source is retrieved via URL. -
getReader
Access to the source contents. -
getInputStream
Access to the source contents. -
getCode
Return the complete text of the code. -
getCode
-
getCode
Gets the text (not including a possible terminating newline) in a (1-based) numbered line. -
getLineCount
public final int getLineCount()The number of text lines in the source, including empty lines; characters at the end of the source without a terminating newline count as a line. -
getLineNumber
Given a 0-based character offset, return the 1-based number of the line that includes the position.- Throws:
IllegalArgumentException
- if the offset is outside the text contents
-
getColumnNumber
Given a 0-based character offset, return the 1-based number of the column at the position.- Throws:
IllegalArgumentException
- if the offset is outside the text contents
-
getLineStartOffset
Given a 1-based line number, return the 0-based offset of the first character in the line.- Throws:
IllegalArgumentException
- if there is no such line in the text
-
getLineLength
The number of characters (not counting a possible terminating newline) in a (1-based) numbered line.- Throws:
IllegalArgumentException
- if there is no such line in the text
-
createSection
public final SourceSection createSection(String identifier, int startLine, int startColumn, int charIndex, int length) Creates a representation of a contiguous region of text in the source.This method performs no checks on the validity of the arguments.
The resulting representation defines hash/equality around equivalent location, presuming that
Source
representations are canonical.- Parameters:
identifier
- terse description of the regionstartLine
- 1-based line number of the first character in the sectionstartColumn
- 1-based column number of the first character in the sectioncharIndex
- the 0-based index of the first character of the sectionlength
- the number of characters in the section- Returns:
- newly created object representing the specified region
-
createSection
public final SourceSection createSection(String identifier, int startLine, int startColumn, int length) Creates a representation of a contiguous region of text in the source. Computes thecharIndex
value by building a map of lines in the source.Checks the position arguments for consistency with the source.
The resulting representation defines hash/equality around equivalent location, presuming that
Source
representations are canonical.- Parameters:
identifier
- terse description of the regionstartLine
- 1-based line number of the first character in the sectionstartColumn
- 1-based column number of the first character in the sectionlength
- the number of characters in the section- Returns:
- newly created object representing the specified region
- Throws:
IllegalArgumentException
- if arguments are outside the text of the sourceIllegalStateException
- if the source is one of the "null" instances
-
createSection
public final SourceSection createSection(String identifier, int charIndex, int length) throws IllegalArgumentException Creates a representation of a contiguous region of text in the source. Computes the(startLine, startColumn)
values by building a map of lines in the source.Checks the position arguments for consistency with the source.
The resulting representation defines hash/equality around equivalent location, presuming that
Source
representations are canonical.- Parameters:
identifier
- terse description of the regioncharIndex
- 0-based position of the first character in the sectionlength
- the number of characters in the section- Returns:
- newly created object representing the specified region
- Throws:
IllegalArgumentException
- if either of the arguments are outside the text of the sourceIllegalStateException
- if the source is one of the "null" instances
-
checkRange
protected void checkRange(int charIndex, int length) -
createSection
Creates a representation of a line of text in the source identified only by line number, from which the character information will be computed.- Parameters:
identifier
- terse description of the linelineNumber
- 1-based line number of the first character in the section- Returns:
- newly created object representing the specified line
- Throws:
IllegalArgumentException
- if the line does not exist the sourceIllegalStateException
- if the source is one of the "null" instances
-
createLineLocation
Creates a representation of a line number in this source, suitable for use as a hash table key with equality defined to mean equivalent location.- Parameters:
lineNumber
- a 1-based line number in this source- Returns:
- a representation of a line in this source
-
createTextMap
protected com.oracle.truffle.api.source.Source.TextMap createTextMap()
-