Package com.oracle.truffle.api.source
Class Source
- java.lang.Object
-
- com.oracle.truffle.api.source.Source
-
public abstract class Source extends java.lang.Object
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.
- Literal: A named text string. These are not indexed and should be considered
value objects; equality is defined based on contents.
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description static Source
asPseudoFile(java.lang.CharSequence chars, java.lang.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)
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.SourceSection
createSection(java.lang.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.SourceSection
createSection(java.lang.String identifier, int charIndex, int length)
Creates a representation of a contiguous region of text in the source.SourceSection
createSection(java.lang.String identifier, int startLine, int startColumn, int length)
Creates a representation of a contiguous region of text in the source.SourceSection
createSection(java.lang.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
createTextMap()
static Source
fromBytes(byte[] bytes, int byteIndex, int length, java.lang.String description, BytesDecoder decoder)
Creates a source from raw bytes.static Source
fromBytes(byte[] bytes, java.lang.String description, BytesDecoder decoder)
Creates a source from raw bytes.static Source
fromFileName(java.lang.String fileName)
Gets the canonical representation of a source file, whose contents will be read lazily and then cached.static Source
fromFileName(java.lang.String fileName, boolean reset)
Gets the canonical representation of a source file, whose contents will be read lazily and then cached.static Source
fromReader(java.io.Reader reader, java.lang.String description)
Creates a source whose contents will be read immediately and cached.static Source
fromText(java.lang.CharSequence chars, java.lang.String description)
Creates a non-canonical source from literal text.static Source
fromURL(java.net.URL url, java.lang.String description)
Creates a source whose contents will be read immediately from a URL and cached.abstract java.lang.String
getCode()
Return the complete text of the code.java.lang.String
getCode(int lineNumber)
Gets the text (not including a possible terminating newline) in a (1-based) numbered line.java.lang.String
getCode(int charIndex, int charLength)
int
getColumnNumber(int offset)
Given a 0-based character offset, return the 1-based number of the column at the position.java.io.InputStream
getInputStream()
Access to the source contents.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.int
getLineLength(int lineNumber)
The number of characters (not counting a possible terminating newline) in a (1-based) numbered line.int
getLineNumber(int offset)
Given a 0-based character offset, return the 1-based number of the line that includes the position.int
getLineStartOffset(int lineNumber)
Given a 1-based line number, return the 0-based offset of the first character in the line.abstract java.lang.String
getName()
Returns the name of this resource holding a guest language program.abstract java.lang.String
getPath()
The normalized, canonical name if the source is a file.abstract java.io.Reader
getReader()
Access to the source contents.abstract java.lang.String
getShortName()
Returns a short version of the name of the resource holding a guest language program (as described in @getName).abstract java.net.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 Detail
-
fromFileName
public static Source fromFileName(java.lang.String fileName, boolean reset) throws java.io.IOException
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:
java.io.IOException
- if the file can not be read
-
fromFileName
public static Source fromFileName(java.lang.String fileName) throws java.io.IOException
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:
java.io.IOException
- if the file can not be read
-
fromText
public static Source fromText(java.lang.CharSequence chars, java.lang.String description)
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
public static Source fromURL(java.net.URL url, java.lang.String description) throws java.io.IOException
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:
java.io.IOException
- if reading fails
-
fromReader
public static Source fromReader(java.io.Reader reader, java.lang.String description) throws java.io.IOException
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:
java.io.IOException
- if reading fails
-
fromBytes
public static Source fromBytes(byte[] bytes, java.lang.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.- 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, java.lang.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
public static Source asPseudoFile(java.lang.CharSequence chars, java.lang.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.- 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
public abstract java.lang.String 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
public abstract java.lang.String 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
public abstract java.lang.String getPath()
The normalized, canonical name if the source is a file.
-
getURL
public abstract java.net.URL getURL()
The URL if the source is retrieved via URL.
-
getReader
public abstract java.io.Reader getReader()
Access to the source contents.
-
getInputStream
public final java.io.InputStream getInputStream()
Access to the source contents.
-
getCode
public abstract java.lang.String getCode()
Return the complete text of the code.
-
getCode
public java.lang.String getCode(int charIndex, int charLength)
-
getCode
public final java.lang.String getCode(int lineNumber)
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
public final int getLineNumber(int offset) throws java.lang.IllegalArgumentException
Given a 0-based character offset, return the 1-based number of the line that includes the position.- Throws:
java.lang.IllegalArgumentException
- if the offset is outside the text contents
-
getColumnNumber
public final int getColumnNumber(int offset) throws java.lang.IllegalArgumentException
Given a 0-based character offset, return the 1-based number of the column at the position.- Throws:
java.lang.IllegalArgumentException
- if the offset is outside the text contents
-
getLineStartOffset
public final int getLineStartOffset(int lineNumber) throws java.lang.IllegalArgumentException
Given a 1-based line number, return the 0-based offset of the first character in the line.- Throws:
java.lang.IllegalArgumentException
- if there is no such line in the text
-
getLineLength
public final int getLineLength(int lineNumber) throws java.lang.IllegalArgumentException
The number of characters (not counting a possible terminating newline) in a (1-based) numbered line.- Throws:
java.lang.IllegalArgumentException
- if there is no such line in the text
-
createSection
public final SourceSection createSection(java.lang.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(java.lang.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:
java.lang.IllegalArgumentException
- if arguments are outside the text of the sourcejava.lang.IllegalStateException
- if the source is one of the "null" instances
-
createSection
public final SourceSection createSection(java.lang.String identifier, int charIndex, int length) throws java.lang.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:
java.lang.IllegalArgumentException
- if either of the arguments are outside the text of the sourcejava.lang.IllegalStateException
- if the source is one of the "null" instances
-
checkRange
protected void checkRange(int charIndex, int length)
-
createSection
public final SourceSection createSection(java.lang.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.- 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:
java.lang.IllegalArgumentException
- if the line does not exist the sourcejava.lang.IllegalStateException
- if the source is one of the "null" instances
-
createLineLocation
public 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.- 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()
-
-