Package com.oracle.truffle.api.source

Class 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.
      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

      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.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • 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 - name
        reset - forces any existing Source 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, 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​(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 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,
                               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 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​(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 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 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 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​(java.lang.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:
        java.lang.IllegalArgumentException - if arguments are outside the text of the source
        java.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 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:
        java.lang.IllegalArgumentException - if either of the arguments are outside the text of the source
        java.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 line
        lineNumber - 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 source
        java.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()