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.
  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
`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()