Package org.pkl.core

Interface Evaluator

  • All Superinterfaces:
    java.lang.AutoCloseable
    All Known Implementing Classes:
    EvaluatorImpl
    public interface Evaluator
extends java.lang.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 Detail

      • 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
        java.lang.IllegalStateException - if this evaluator has already been closed

      • evaluateOutputText

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

      • evaluateOutputValue

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

      • evaluateOutputFiles

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

      • evaluateExpression

        java.lang.Object evaluateExpression​(ModuleSource moduleSource,
                                    java.lang.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

        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
        java.lang.IllegalStateException - if this evaluator has already been closed

      • evaluateExpressionString

        java.lang.String evaluateExpressionString​(ModuleSource moduleSource,
                                          java.lang.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
        java.lang.IllegalStateException - if this evaluator has already been closed

      • evaluateSchema

        ModuleSchema evaluateSchema​(ModuleSource moduleSource)
        Evalautes the module's schema, which describes the properties, methods, and classes of a module.
        Throws:
        PklException - if an error occurs during evaluation
        java.lang.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
        java.lang.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 pcf-expected.pkl and pcf-actual.pcf files as a sibling of the test module. The overwrite parameter causes the evaluator to overwrite pcf-expected.pkl files if they currently exist.

        Throws:
        PklException - if an error occurs during evaluation
        java.lang.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 java.lang.AutoCloseable