public class Source.SourceBuilder extends Object
creating
new
Source
instance.
To load a source from disk one can use:
assert file.getName().endsWith(".java") : "Imagine 'c:\\sources\\Example.java' file";String
language =Source
.findLanguage(file);Source
source =Source
.newBuilder(language, file).build(); assert file.getName().equals(source.getName()); assert file.getPath().equals(source.getPath()); assert file.toUri().equals(source.getURI());
To load source from a URL
one can use:
URL
resource = relativeClass.getResource("sample.js");Source
source =Source
.newBuilder("js", resource) .build(); assert resource.toExternalForm().equals(source.getPath()); assert "sample.js".equals(source.getName()); assert resource.toURI().equals(source.getURI());
To create a source representing characters:
Source
source =Source
.newBuilder("js", "function() {\n" + " return 'Hi';\n" + "}\n", "hi.js").build(); assert "hi.js".equals(source.getName());
or read a source from a Reader
:
Reader
stream = newInputStreamReader
( relativeClass.getResourceAsStream("sample.js") );Source
source =Source
.newBuilder("js", stream, "sample.js") .build(); assert "sample.js".equals(source.getName());
To create a source representing bytes:
byte[] bytes = new byte[] {/* Binary */};Once your builder is configured, callSource
source =Source
.newBuilder("llvm",ByteSequence
.create(bytes), "<literal>").build();
Source.SourceBuilder.build()
to perform the loading and
construction of new Source
.Modifier and Type | Method and Description |
---|---|
Source |
build()
Uses configuration of this builder to create new
Source object. |
Source.SourceBuilder |
cached(boolean enabled)
Enables or disables code caching for this source.
|
Source.SourceBuilder |
canonicalizePath(boolean canonicalize)
Whether the
Source.getPath() (from the TruffleFile ) should be
canonicalized. |
Source.LiteralBuilder |
content(ByteSequence bytes)
Specifies byte based content of
to-be-built Source . |
Source.LiteralBuilder |
content(CharSequence characters)
Specifies character based content of
to-be-built Source . |
Source.SourceBuilder |
encoding(Charset encoding)
Explicitly assigns an encoding used to read the file content.
|
Source.SourceBuilder |
interactive(boolean enabled)
Marks the source as interactive.
|
Source.SourceBuilder |
internal(boolean enabled)
Marks the source as internal.
|
Source.SourceBuilder |
mimeType(String mimeType)
|
Source.SourceBuilder |
name(String newName)
Specifies a name to the
to-be-built Source . |
Source.SourceBuilder |
uri(URI ownUri)
|
public Source.SourceBuilder name(String newName)
to-be-built
Source
.newName
- name that replaces the previously given one. If set to null
then "Unnamed"
will be used.this
builderpublic Source.LiteralBuilder content(CharSequence characters)
to-be-built
Source
. Using
this method one can ignore the real content of a file or URL and use already read one, or
completely different one. Use Source.CONTENT_NONE
to set no content,
Source.hasCharacters()
will be false
then. The given characters must
not mutate after they were accessed for the first time. Example:
URL
resource = relativeClass.getResource("sample.js");Source
source =Source
.newBuilder("js", resource) .content("{}") .build(); assert resource.toExternalForm().equals(source.getPath()); assert "sample.js".equals(source.getName()); assert resource.toExternalForm().equals(source.getURI().toString()); assert "{}".equals(source.getCharacters());
characters
- the code to be available via Source.getCharacters()
, or
Source.CONTENT_NONE
Source.SourceBuilder.build()
method no longer throws an
IOException
public Source.LiteralBuilder content(ByteSequence bytes)
to-be-built
Source
. Using this
method one can ignore the real content of a file or URL and use already read one, or
completely different one. The given bytes must not mutate after they were accessed for
the first time. Example:
URL
resource = relativeClass.getResource("sample.js");Source
source =Source
.newBuilder("js", resource) .content("{}") .build(); assert resource.toExternalForm().equals(source.getPath()); assert "sample.js".equals(source.getName()); assert resource.toExternalForm().equals(source.getURI().toString()); assert "{}".equals(source.getCharacters());
bytes
- the code to be available via Source.getBytes()
Source.SourceBuilder.build()
method no longer throws an
IOException
public Source.SourceBuilder mimeType(String mimeType)
MIME type
to the to-be-built
Source
. If the MIME type is null
then the
default MIME type
of the language will be used to
interpret the source. If set explicitly then the language needs to
support
the MIME type in order to
parse
a
source. If not null
then the MIME type will be verified containing no spaces
and a '/' between group and sub-group. An example for a valid MIME type is:
text/javascript
.
The MIME type can be guessed by the system based on files
or urls
.
mimeType
- the new mime type to be assigned, or null
if default MIME
type should be used.this
builder ready to create new source
LanguageInfo.getDefaultMimeType()
,
LanguageInfo.getMimeTypes()
,
Source.findMimeType(TruffleFile)
,
Source.findMimeType(URL)
public Source.SourceBuilder cached(boolean enabled)
true
then the source does not require parsing every time this source is
evaluated. If false
then the source requires parsing every time the source
is evaluated but does not remember any code. Disabling caching may be useful if the
source is known to only be evaluated once.
If a source instance is no longer referenced by the client then all code caches will be freed automatically. Also, if the underlying context or engine is no longer referenced then cached code for evaluated sources will be freed automatically.
this
builder ready to create new source
public Source.SourceBuilder internal(boolean enabled)
Source.isInternal()
public Source.SourceBuilder interactive(boolean enabled)
interactive
language
can use the environment
streams to print the result and read an input. However, non-interactive languages are
expected to ignore the interactive property of sources and not use the environment
streams. Any desired printing of the evaluated result provided by a non-interactive
language needs to be handled by the caller. Calling of this method influences the result
of Source.isInteractive()
.public Source.SourceBuilder uri(URI ownUri)
URI
to the to-be-created
Source
. Each source
provides Source.getURI()
as a persistent identification of its location. A
default value for the method is deduced from the location or content, but one can change
it by using this methodownUri
- the URL to use instead of default one, cannot be null
public Source.SourceBuilder canonicalizePath(boolean canonicalize)
Source.getPath()
(from the TruffleFile
) should be
canonicalized. By default the path is canonicalized to improve Source caching. If set to
false
, then Source.getPath()
will be the same as the passed TruffleFile
TruffleFile.getPath()
.canonicalize
- whether to canonicalize the path from the the TruffleFilepublic Source.SourceBuilder encoding(Charset encoding)
null
then the file contained encoding information is used. If the file doesn't
provide an encoding information the default UTF-8
encoding is used.encoding
- the new file encoding to be used for reading the contentthis
builder ready to create new source
public Source build() throws IOException
Source
object. The method throws
an IOException
if an error loading the source occurred.IOException
- if an error reading the content occurredSecurityException
- if the used filesystem
denied file reading