Package org.pkl.core

Class EvaluatorBuilder

java.lang.Object

org.pkl.core.EvaluatorBuilder

public final class EvaluatorBuilder
extends Object

A builder for an Evaluator. Can be reused to build multiple evaluators.

Method Summary

Modifier and Type	Method	Description
EvaluatorBuilder	addEnvironmentVariable(String name, String value)	Adds the given environment variable, overriding any environment variable previously added under the same name.
EvaluatorBuilder	addEnvironmentVariables(Map<String,String> envVars)	Adds the given environment variables, overriding any environment variables previously added under the same name.
EvaluatorBuilder	addExternalProperties(Map<String,String> properties)	Adds the given external properties, overriding any properties previously set under the same name.
EvaluatorBuilder	addExternalProperty(String name, String value)	Adds the given external property, overriding any property previously set under the same name.
EvaluatorBuilder	addModuleKeyFactories(Collection<ModuleKeyFactory> factories)	Adds the given module key factories.
EvaluatorBuilder	addModuleKeyFactory(ModuleKeyFactory factory)	Adds the given module key factory.
EvaluatorBuilder	addResourceReader(ResourceReader reader)
EvaluatorBuilder	addResourceReaders(Collection<ResourceReader> readers)
EvaluatorBuilder	applyFromProject(Project project)	Given a project, sets its dependencies, and also applies any evaluator settings if set.
Evaluator	build()
List<Pattern>	getAllowedModules()	Returns the set of patterns to be allowed when importing modules.
List<Pattern>	getAllowedResources()	Returns the set of patterns to be allowed when reading resources.
boolean	getColor()	Returns the current setting of the option to render errors in ANSI color.
Map<String,String>	getEnvironmentVariables()	Returns the currently set environment variables.
Map<String,String>	getExternalProperties()	Returns the currently set external properties.
HttpClient	getHttpClient()	Returns the currently set HTTP client.
Logger	getLogger()	Returns the currently set logger.
@Nullable Path	getModuleCacheDir()	Returns the directory where `package:` modules are cached.
List<ModuleKeyFactory>	getModuleKeyFactories()	Returns the currently set module key factories.
@Nullable String	getOutputFormat()	Returns the currently set output format, if any.
@Nullable DeclaredDependencies	getProjectDependencies()
List<ResourceReader>	getResourceReaders()	Returns the currently set resource readers.
@Nullable Path	getRootDir()	Returns the currently set root directory, if set.
@Nullable SecurityManager	getSecurityManager()	Returns the currently set security manager.
@Nullable StackFrameTransformer	getStackFrameTransformer()	Returns the currently set stack frame transformer.
@Nullable Duration	getTimeout()	Returns the currently set evaluation timeout.
TraceMode	getTraceMode()	Returns whether calls to trace() produce indented, multi-line output.
static EvaluatorBuilder	preconfigured()	Creates a builder preconfigured with: SecurityManagers.defaultAllowedModules SecurityManagers.defaultAllowedResources Loggers.noop() ModuleKeyFactories.standardLibrary ModuleKeyFactories.classPath(java.lang.ClassLoader) ModuleKeyFactories.fromServiceProviders() ModuleKeyFactories.file ModuleKeyFactories.pkg ModuleKeyFactories.projectpackage ModuleKeyFactories.genericUrl ResourceReaders.environmentVariable() ResourceReaders.externalProperty() ResourceReaders.classPath(java.lang.ClassLoader) ResourceReaders.file() ResourceReaders.http() ResourceReaders.https() ResourceReaders.pkg() ResourceReaders.projectpackage() ResourceReaders.fromServiceProviders() System.getProperties()
EvaluatorBuilder	setAllowedModules(Collection<Pattern> patterns)	Sets the set of URI patterns to be allowed when importing modules.
EvaluatorBuilder	setAllowedResources(Collection<Pattern> patterns)	Sets the set of URI patterns to be allowed when reading resources.
EvaluatorBuilder	setColor(boolean color)	Sets the option to render errors in ANSI color.
EvaluatorBuilder	setEnvironmentVariables(Map<String,String> envVars)	Removes any existing environment variables, then adds the given environment variables.
EvaluatorBuilder	setExternalProperties(Map<String,String> properties)	Removes any existing external properties, then adds the given properties.
EvaluatorBuilder	setHttpClient(HttpClient httpClient)	Sets the HTTP client to be used.
EvaluatorBuilder	setLogger(Logger logger)	Sets the given logger, replacing any previously set logger.
EvaluatorBuilder	setModuleCacheDir(@Nullable Path moduleCacheDir)	Sets the directory where `package:` modules are cached.
EvaluatorBuilder	setModuleKeyFactories(Collection<ModuleKeyFactory> factories)	Removes any existing module key factories, then adds the given factories.
EvaluatorBuilder	setOutputFormat(@Nullable String outputFormat)	Sets the desired output format, if any.
EvaluatorBuilder	setOutputFormat(@Nullable OutputFormat outputFormat)	Sets the desired output format, if any.
EvaluatorBuilder	setProjectDependencies(DeclaredDependencies dependencies)	Sets the project dependencies for the evaluator.
EvaluatorBuilder	setResourceReaders(Collection<ResourceReader> readers)
EvaluatorBuilder	setRootDir(@Nullable Path rootDir)	Sets the root directory, which restricts access to file-based modules and resources located under this directory.
EvaluatorBuilder	setSecurityManager(@Nullable SecurityManager manager)	Sets the given security manager, replacing any previously set security manager.
EvaluatorBuilder	setStackFrameTransformer(StackFrameTransformer stackFrameTransformer)	Sets the given stack frame transformer, replacing any previously set transformer.
EvaluatorBuilder	setTimeout(Duration timeout)	Sets an evaluation timeout to be enforced by the Evaluator's evaluate methods.
EvaluatorBuilder	setTraceMode(TraceMode traceMode)	Sets whether calls to trace() produce indented, multi-line output.
static EvaluatorBuilder	unconfigured()	Creates a builder that is unconfigured.
EvaluatorBuilder	unsetSecurityManager()

Methods inherited from class java.lang.Object

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

Method Details

preconfigured

public static EvaluatorBuilder preconfigured()

Creates a builder preconfigured with:

• SecurityManagers.defaultAllowedModules
• SecurityManagers.defaultAllowedResources
• Loggers.noop()
• ModuleKeyFactories.standardLibrary
• ModuleKeyFactories.classPath(java.lang.ClassLoader)
• ModuleKeyFactories.fromServiceProviders()
• ModuleKeyFactories.file
• ModuleKeyFactories.pkg
• ModuleKeyFactories.projectpackage
• ModuleKeyFactories.genericUrl
• ResourceReaders.environmentVariable()
• ResourceReaders.externalProperty()
• ResourceReaders.classPath(java.lang.ClassLoader)
• ResourceReaders.file()
• ResourceReaders.http()
• ResourceReaders.https()
• ResourceReaders.pkg()
• ResourceReaders.projectpackage()
• ResourceReaders.fromServiceProviders()
• System.getProperties()

unconfigured

public static EvaluatorBuilder unconfigured()

Creates a builder that is unconfigured. At a minimum, a security manager will need to be set before building an instance.

setColor

public EvaluatorBuilder setColor(boolean color)

Sets the option to render errors in ANSI color.

getColor

public boolean getColor()

Returns the current setting of the option to render errors in ANSI color.

setStackFrameTransformer

public EvaluatorBuilder setStackFrameTransformer(StackFrameTransformer stackFrameTransformer)

Sets the given stack frame transformer, replacing any previously set transformer.

getStackFrameTransformer

@Nullable
public @Nullable StackFrameTransformer getStackFrameTransformer()

Returns the currently set stack frame transformer.

setSecurityManager

public EvaluatorBuilder setSecurityManager(@Nullable
 @Nullable SecurityManager manager)

Sets the given security manager, replacing any previously set security manager.

unsetSecurityManager

public EvaluatorBuilder unsetSecurityManager()

getSecurityManager

@Nullable
public @Nullable SecurityManager getSecurityManager()

Returns the currently set security manager.

setAllowedModules

public EvaluatorBuilder setAllowedModules(Collection<Pattern> patterns)

Sets the set of URI patterns to be allowed when importing modules.

Throws:

IllegalStateException - if setSecurityManager(SecurityManager) was also called.

getAllowedModules

public List<Pattern> getAllowedModules()

Returns the set of patterns to be allowed when importing modules.

setAllowedResources

public EvaluatorBuilder setAllowedResources(Collection<Pattern> patterns)

Sets the set of URI patterns to be allowed when reading resources.

Throws:

IllegalStateException - if setSecurityManager(SecurityManager) was also called.

getAllowedResources

public List<Pattern> getAllowedResources()

Returns the set of patterns to be allowed when reading resources.

setRootDir

public EvaluatorBuilder setRootDir(@Nullable
 @Nullable Path rootDir)

Sets the root directory, which restricts access to file-based modules and resources located under this directory.

getRootDir

@Nullable
public @Nullable Path getRootDir()

Returns the currently set root directory, if set.

setLogger

public EvaluatorBuilder setLogger(Logger logger)

Sets the given logger, replacing any previously set logger.

getLogger

public Logger getLogger()

Returns the currently set logger.

setHttpClient

public EvaluatorBuilder setHttpClient(HttpClient httpClient)

Sets the HTTP client to be used.

Defaults to HttpClient.builder().buildLazily().

getHttpClient

public HttpClient getHttpClient()

Returns the currently set HTTP client.

addModuleKeyFactory

public EvaluatorBuilder addModuleKeyFactory(ModuleKeyFactory factory)

Adds the given module key factory. Factories will be asked to resolve module keys in the order they have been added to this builder.

addModuleKeyFactories

public EvaluatorBuilder addModuleKeyFactories(Collection<ModuleKeyFactory> factories)

Adds the given module key factories. Factories will be asked to resolve module keys in the order they have been added to this builder.

setModuleKeyFactories

public EvaluatorBuilder setModuleKeyFactories(Collection<ModuleKeyFactory> factories)

Removes any existing module key factories, then adds the given factories.

getModuleKeyFactories

public List<ModuleKeyFactory> getModuleKeyFactories()

Returns the currently set module key factories.

addResourceReader

public EvaluatorBuilder addResourceReader(ResourceReader reader)

addResourceReaders

public EvaluatorBuilder addResourceReaders(Collection<ResourceReader> readers)

setResourceReaders

public EvaluatorBuilder setResourceReaders(Collection<ResourceReader> readers)

getResourceReaders

public List<ResourceReader> getResourceReaders()

Returns the currently set resource readers.

addEnvironmentVariable

public EvaluatorBuilder addEnvironmentVariable(String name,
 String value)

Adds the given environment variable, overriding any environment variable previously added under the same name.

Pkl code can read environment variables with read("env:<NAME>").

addEnvironmentVariables

public EvaluatorBuilder addEnvironmentVariables(Map<String,String> envVars)

Adds the given environment variables, overriding any environment variables previously added under the same name.

Pkl code can read environment variables with read("env:<NAME>").

setEnvironmentVariables

public EvaluatorBuilder setEnvironmentVariables(Map<String,String> envVars)

Removes any existing environment variables, then adds the given environment variables.

getEnvironmentVariables

public Map<String,String> getEnvironmentVariables()

Returns the currently set environment variables.

addExternalProperty

public EvaluatorBuilder addExternalProperty(String name,
 String value)

Adds the given external property, overriding any property previously set under the same name.

Pkl code can read external properties with read("prop:<name>").

addExternalProperties

public EvaluatorBuilder addExternalProperties(Map<String,String> properties)

Adds the given external properties, overriding any properties previously set under the same name.

Pkl code can read external properties with read("prop:<name>").

setExternalProperties

public EvaluatorBuilder setExternalProperties(Map<String,String> properties)

Removes any existing external properties, then adds the given properties.

getExternalProperties

public Map<String,String> getExternalProperties()

Returns the currently set external properties.

setTimeout

public EvaluatorBuilder setTimeout(@Nullable
 Duration timeout)

Sets an evaluation timeout to be enforced by the Evaluator's evaluate methods.

getTimeout

public @Nullable Duration getTimeout()

Returns the currently set evaluation timeout.

setModuleCacheDir

public EvaluatorBuilder setModuleCacheDir(@Nullable
 @Nullable Path moduleCacheDir)

Sets the directory where `package:` modules are cached.

If null, the module cache is disabled.

getModuleCacheDir

@Nullable
public @Nullable Path getModuleCacheDir()

Returns the directory where `package:` modules are cached. If null, the module cache is disabled.

setOutputFormat

public EvaluatorBuilder setOutputFormat(@Nullable
 @Nullable String outputFormat)

Sets the desired output format, if any.

By default, modules support the formats described by OutputFormat. and fall back to OutputFormat.PCF if no format is specified.

Modules that override output.renderer in their source code may ignore this option or may support formats other than those described by OutputFormat. In particular, most templates ignore this option and always render the same format.

setOutputFormat

public EvaluatorBuilder setOutputFormat(@Nullable
 @Nullable OutputFormat outputFormat)

Sets the desired output format, if any.

By default, modules support the formats described by OutputFormat. and fall back to OutputFormat.PCF if no format is specified.

Modules that override output.renderer in their source code may ignore this option or may support formats other than those described by OutputFormat. In particular, most templates ignore this option and always render the same format.

getOutputFormat

@Nullable
public @Nullable String getOutputFormat()

Returns the currently set output format, if any.

setProjectDependencies

public EvaluatorBuilder setProjectDependencies(DeclaredDependencies dependencies)

Sets the project dependencies for the evaluator.

getProjectDependencies

@Nullable
public @Nullable DeclaredDependencies getProjectDependencies()

setTraceMode

public EvaluatorBuilder setTraceMode(TraceMode traceMode)

Sets whether calls to trace() produce indented, multi-line output.

getTraceMode

public TraceMode getTraceMode()

Returns whether calls to trace() produce indented, multi-line output.

applyFromProject

public EvaluatorBuilder applyFromProject(Project project)

Given a project, sets its dependencies, and also applies any evaluator settings if set.

Throws:

IllegalStateException - if setSecurityManager(SecurityManager) was also called.

build

public Evaluator build()