Class Source

java.lang.Object
com.oracle.truffle.api.source.Source

public abstract class Source extends 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.
    See fromText(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.
    See fromFileName(String)
    See fromFileName(String, boolean)
  • URL: Each URL source is represented as a canonical object, indexed by the URL. Contents are read eagerly and cached.
    See fromURL(URL, String)
  • Reader: Contents are read eagerly and treated as a Literal .
    See fromReader(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.
    See asPseudoFile(CharSequence, String)

File cache:

  1. File content caching is optional, off by default.
  2. The first access to source file contents will result in the contents being read, and (if enabled) cached.
  3. If file contents have been cached, access to contents via getInputStream() or getReader() will be provided from the cache.
  4. Any access to file contents via the cache will result in a timestamp check and possible cache reload.
  • Method Summary

    Modifier and Type
    Method
    Description
    static 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)
     
    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.
    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.
    createSection(String identifier, int charIndex, int length)
    Creates a representation of a contiguous region of text in the source.
    createSection(String identifier, int startLine, int startColumn, int length)
    Creates a representation of a contiguous region of text in the source.
    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
    fromURL(URL url, String description)
    Creates a source whose contents will be read immediately from a URL and cached.
    abstract String
    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.
    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
    Returns the name of this resource holding a guest language program.
    abstract String
    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
    The URL if the source is retrieved via URL.
    protected abstract void
     
    static void
    setFileCaching(boolean enabled)
    Enables/disables caching of file contents, disabled by default.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Method Details

    • fromFileName

      public static Source fromFileName(String fileName, boolean reset) throws IOException
      Gets the canonical representation of a source file, whose contents will be read lazily and then cached.
      Parameters:
      fileName - name
      reset - forces any existing Source 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

      public static Source fromFileName(String fileName) throws 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:
      IOException - if the file can not be read
    • fromText

      public static Source fromText(CharSequence chars, String description)
      Creates a non-canonical source from literal text. If an already created literal source must be retrievable by name, use asPseudoFile(CharSequence, String).
      Parameters:
      chars - textual source code
      description - a note about the origin, for error messages and debugging
      Returns:
      a newly created, non-indexed source representation
    • fromURL

      public static Source fromURL(URL url, String description) throws 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:
      IOException - if reading fails
    • fromReader

      public static Source fromReader(Reader reader, String description) throws 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:
      IOException - if reading fails
    • fromBytes

      public static Source fromBytes(byte[] bytes, 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 source
      description - a note about the origin, possibly useful for debugging
      decoder - 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 source
      byteIndex - where the string starts in the byte array
      length - the length of the string in the byte array
      description - a note about the origin, possibly useful for debugging
      decoder - how to decode the bytes into Java strings
      Returns:
      a newly created, non-indexed source representation
    • asPseudoFile

      public static 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.
      Parameters:
      chars - textual source code
      pseudoFileName - 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 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 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 String getPath()
      The normalized, canonical name if the source is a file.
    • getURL

      public abstract URL getURL()
      The URL if the source is retrieved via URL.
    • getReader

      public abstract Reader getReader()
      Access to the source contents.
    • getInputStream

      public final InputStream getInputStream()
      Access to the source contents.
    • getCode

      public abstract String getCode()
      Return the complete text of the code.
    • getCode

      public String getCode(int charIndex, int charLength)
    • getCode

      public final 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 IllegalArgumentException
      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

      public final int getColumnNumber(int offset) throws IllegalArgumentException
      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

      public final int getLineStartOffset(int lineNumber) throws IllegalArgumentException
      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

      public final int getLineLength(int lineNumber) throws IllegalArgumentException
      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 region
      startLine - 1-based line number of the first character in the section
      startColumn - 1-based column number of the first character in the section
      charIndex - the 0-based index of the first character of the section
      length - 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 the charIndex 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 region
      startLine - 1-based line number of the first character in the section
      startColumn - 1-based column number of the first character in the section
      length - 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 source
      IllegalStateException - 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 region
      charIndex - 0-based position of the first character in the section
      length - 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 source
      IllegalStateException - if the source is one of the "null" instances
    • checkRange

      protected void checkRange(int charIndex, int length)
    • createSection

      public 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.
      Parameters:
      identifier - terse description of the line
      lineNumber - 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 source
      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()