Package org.pkl.core

Interface Evaluator

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
EvaluatorImpl
public interface Evaluator extends AutoCloseable
Evaluates a Pkl module through different modes of evaluation. Throws VmEvalException if an error occurs during evaluation.

Evaluated modules, and modules imported by them, are cached based on their origin. This is important to guarantee consistent evaluation results, for example when the same module is used by multiple other modules. To reset the cache, close() the current instance and create a new one.

Construct an evaluator through EvaluatorBuilder.

  • Method Details

    • preconfigured

      static Evaluator preconfigured()
      Shorthand for EvaluatorBuilder.preconfigured().build().

    • evaluate

      PModule evaluate(ModuleSource moduleSource)
      Evaluates the module, returning the Java representation of the module object.
      Throws:
      PklException - if an error occurs during evaluation
      IllegalStateException - if this evaluator has already been closed

    • evaluateOutputText

      String evaluateOutputText(ModuleSource moduleSource)
      Evaluates a module's output.text property.
      Throws:
      PklException - if an error occurs during evaluation
      IllegalStateException - if this evaluator has already been closed

    • evaluateOutputBytes

      byte[] evaluateOutputBytes(ModuleSource moduleSource)
      Evaluates a module's output.bytes property.
      Throws:
      PklException - if an error occurs during evaluation
      IllegalStateException - if this evaluator has already been closed
      Since:
      0.29.0

    • evaluateOutputValue

      Object evaluateOutputValue(ModuleSource moduleSource)
      Evaluates a module's output.value property.
      Throws:
      PklException - if an error occurs during evaluation
      IllegalStateException - if this evaluator has already been closed

    • evaluateOutputFiles

      Map<String,FileOutput> evaluateOutputFiles(ModuleSource moduleSource)
      Evaluates a module's output.files property.
      Throws:
      PklException - if an error occurs during evaluation
      IllegalStateException - if this evaluator has already been closed

    • evaluateExpression

      Object evaluateExpression(ModuleSource moduleSource, String expression)
      Evaluates the Pkl expression represented as expression, returning the Java representation of the result.

      The following table describes how Pkl types are represented in Java:

      Pkl type Java type
      Null PNull
      String String
      Boolean Boolean
      Int Long
      Float Double
      Typed, Dynamic PObject (PModule if the object is a module)
      Mapping, Map Map
      Listing, List List
      Set Set
      Pair Pair
      Regex Pattern
      DataSize DataSize
      Duration Duration
      Class PClass
      TypeAlias TypeAlias
      Bytes byte[]

      The following Pkl types have no Java representation, and an error is thrown if an expression computes to a value of these types:

      • IntSeq
      • Function
      Throws:
      PklException - if an error occurs during evaluation
      IllegalStateException - if this evaluator has already been closed

    • evaluateExpressionPklBinary

      byte[] evaluateExpressionPklBinary(ModuleSource moduleSource, String expression)
      Evaluates the Pkl expression represented as expression, returning a byte array of the pkl-binary-encoded representation of the result.
      Throws:
      PklException - if an error occurs during evaluation
      IllegalStateException - if this evaluator has already been closed

    • evaluateExpressionString

      String evaluateExpressionString(ModuleSource moduleSource, String expression)
      Evaluates the Pkl expression, returning the stringified result.

      This is equivalent to wrapping the expression with .toString()

      Throws:
      PklException - if an error occurs during evaluation
      IllegalStateException - if this evaluator has already been closed

    • evaluateSchema

      ModuleSchema evaluateSchema(ModuleSource moduleSource)
      Evaluates the module's schema, which describes the properties, methods, and classes of a module.
      Throws:
      PklException - if an error occurs during evaluation
      IllegalStateException - if this evaluator has already been closed

    • evaluateOutputValueAs

      <T> T evaluateOutputValueAs(ModuleSource moduleSource, PClassInfo<T> classInfo)
      Evaluates the module's output.value property, and validates that its type matches the provided class info.
      Throws:
      PklException - if an error occurs during evaluation
      IllegalStateException - if this evaluator has already been closed

    • evaluateTest

      TestResults evaluateTest(ModuleSource moduleSource, boolean overwrite)
      Runs tests within the module, and returns the test results.

      This requires that the target module be a test module; it must either amend or extend module "pkl:test". Otherwise, a type mismatch error is thrown.

      This method will write possibly pkl-expected.pcf and pkl-actual.pcf files as a sibling of the test module. The overwrite parameter causes the evaluator to overwrite pkl-expected.pkl files if they currently exist.

      Throws:
      PklException - if an error occurs during evaluation
      IllegalStateException - if this evaluator has already been closed

    • close

      void close()
      Releases all resources held by this evaluator. If an evaluate method is currently executing, this method blocks until cancellation of that execution has completed.

      Once an evaluator has been closed, it can no longer be used, and calling evaluate methods will throw IllegalStateException. However, objects previously returned by evaluate methods remain valid.

      Specified by:
      close in interface AutoCloseable