Graal Sdk 23.1.1 · org.graalvm.polyglot.Source · APIdia, the JavaDoc alternative

Representation of a source code unit and its contents that can be evaluated in an execution context. Each source is associated with the the ID of the language.

From a file on disk

Each file is represented as a canonical object, indexed by the absolute, canonical path name of the file. File content is read eagerly and may be optionally cached. Sample usage:
SourceSnippets#fromFile The starting point is Source#newBuilder(String, java.io.File) method.

Read from a URL

One can read remote or in JAR resources using the Source#newBuilder(String, java.net.URL) factory:
SourceSnippets#fromURL Each URL source is represented as a canonical object, indexed by the URL. Contents are read eagerly once the Builder#build() method is called.

Source from a literal text

An anonymous immutable code snippet can be created from a string via the Source#newBuilder(String, java.lang.CharSequence, String) factory method:
SourceSnippets#fromAString

Reading from a stream

If one has a Reader one can convert its content into a Source via Source#newBuilder(String, java.io.Reader, String) method:
SourceSnippets#fromReader the content is read eagerly once the Builder#build() method is called.

Reading from bytes

Sources can be created from bytes. Please note that all character related methods will throw an UnsupportedOperationException if that is the case. SourceSnippets#fromBytes

Attributes

The source object can be associated with various attributes like getName() and getURI(), getMimeType() and these are immutable. The system makes the best effort to derive values of these attributes from the location and/or content of the Source object. However, to give the user that creates the source control over these attributes, the API offers an way to alter values of these attributes.

Character and byte based Sources

A source is byte or character based, or none of those when no content is specified. For literal sources it depends on whether the byte or character based factory method was used. When the source was loaded from a file or url then the default MIME type of the provided language will be used to determine whether bytes or characters should be loaded. The behavior can be customized by specifying a MIME type or content explicitly. If the specified or inferred MIME type starts with 'text/ or the MIME types is null then it will be interpreted as character based, otherwise byte based.

Modifier and Type	Class and Description
public class	Source.Builder Represents a builder to build `Source` objects.

Modifier and Type	Field and Description
pack-priv final AbstractPolyglotImpl.AbstractSourceDispatch	dispatch
private static final Source	EMPTY
private static volatile AbstractPolyglotImpl	IMPL
pack-priv final Object	receiver

Access	Constructor and Description
pack-priv	Source(AbstractPolyglotImpl.AbstractSourceDispatch dispatch, Object receiver)

Method Summary

Modifier and Type	Method and Description
public static Source	create(String language, CharSequence source) Shortcut for creating a source object from a language and char sequence.
public boolean	equals(Object the reference object with which to compare. obj) Overrides java.lang.Object.equals. Indicates whether some other object is "equal to" this one.
public static String	findLanguage(File the file to find the first language for file) Returns the id of the first language that supports evaluating the probed mime type of a given `file`.
public static String	findLanguage(URL the url to find the first language for url) Returns the id of the first language that supports evaluating the probed mime type of a given `URL`.
public static String	findLanguage(String mimeType) Returns the first installed language that supports evaluating sources for a given MIME type.
public static String	findMimeType(File file) Returns the probed MIME type for a given file, or `null` if no MIME type could be resolved.
public static String	findMimeType(URL url) Returns the probed MIME type for a given url, or `null` if no MIME type could be resolved.
public ByteSequence	getBytes() Returns the bytes of the source if it is a `byte based source`.
public CharSequence	getCharacters() Returns all characters of the source.
public CharSequence	getCharacters(int lineNumber) Gets the text (not including a possible terminating newline) in a (1-based) numbered line.
public int	getColumnNumber(int offset) Given a 0-based character offset, return the 1-based number of the column at the position.
pack-priv static AbstractPolyglotImpl	getImpl()
public InputStream	getInputStream() Deprecated since 19.0. use `getReader()`, `getCharacters()` or `getBytes()` instead.
public String	getLanguage() Returns the language this source created with.
public int	getLength() Gets the number of characters or bytes of the source.
public int	getLineCount() The number of text lines of a character based source, including empty lines; characters at the end of the source without a terminating newline count as a line.
public int	getLineLength(int lineNumber) The number of characters (not counting a possible terminating newline) in a (1-based) numbered line.
public int	getLineNumber(int offset) Given a 0-based character offset, return the 1-based number of the line that includes the position.
public int	getLineStartOffset(int lineNumber) Given a 1-based line number, return the 0-based offset of the first character in the line.
public String	Returns: MIME type of this source or `null`, if not explicitly set. getMimeType() Returns the MIME type that is associated with this source.
public String	Returns: the name of the guest language program getName() Returns the name of this resource holding a guest language program.
public String	getPath() The fully qualified name of the source.
public Reader	getReader() Returns a new reader that reads from the `characters` provided by this source.
public URI	Returns: a URI, never `null` getURI() Get the URI of the source.
public URL	Returns: URL or `null` getURL() The URL if the source is retrieved via URL.
public boolean	hasBytes() Returns `true` if this source represents a byte based source, else `false`.
public boolean	hasCharacters() Returns `true` if this source represents a character based source, else `false`.
public int	hashCode() Overrides java.lang.Object.hashCode. Returns a hash code value for the object.
private static IllegalArgumentException	invalidMimeType(String mimeType)
public boolean	Returns: whether this source is marked as interactive isInteractive() Check whether this source has been marked as interactive.
public boolean	Returns: whether this source is marked as internal isInternal() Gets whether this source has been marked as internal, meaning that it has been provided by the infrastructure, language implementation, or system library.
public static Source.Builder	newBuilder(String the language id, must not be `null` language, CharSequence the character sequence or string, must not be `null` characters, String the name of the source, if `null` then `"Unnamed"` will be used as name. name) Creates a new character based literal source from a character sequence.
public static Source.Builder	newBuilder(String the language id, must not be `null` language, ByteSequence the byte sequence or string, must not be `null` bytes, String the name of the source, if `null` then `"Unnamed"` will be used as name. name) Creates a new byte based literal source from a byte sequence.
public static Source.Builder	newBuilder(String the language id, must not be `null` language, File the file to use, must not be `null` file) Creates a new file based source builder from a given file.
public static Source.Builder	newBuilder(String the language id, must not be `null` language, URL the URL to use and load, must not be `null` url) Creates a new URL based source builder from a given URL.
public static Source.Builder	newBuilder(String language, Reader source, String name) Creates new character based literal source from a reader.
pack-priv static <E extends Exception> RuntimeException	silenceException(Class<E> type, Exception ex)
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.
private static void	validateMimeType(String mimeType)

Inherited from java.lang.Object:: clone finalize getClass notify notifyAll wait wait wait

public final Class Source