"kernel.evalBuilder(..)" #111

Author: andrus

RELEASE-NOTES.md

@@ -6,6 +6,7 @@
 * #105 Exploding classpath
 * #107 "java.class.path" uses an incorrect separator
 * #110 Magic return values are suppressed
+* #111 "kernel.evalBuilder(..)"
 
 ## 1.0-a6
 

jjava-distro/src/main/java/org/dflib/jjava/distro/JJava.java

@@ -79,7 +79,7 @@ public static void main(String[] args) throws Exception {
         kernel.addToClasspath(Env.extraClasspath());
 
         // run user defined startup snippets explicitly after the default startup
-        Env.startupSnippets().forEach(kernel::evalRaw);
+        Env.startupSnippets().forEach(s -> kernel.evalBuilder(s).resolveMagics().eval());
 
         // connect to Jupyter
         kernel.becomeHandlerForConnection(connection);

jjava-distro/src/main/java/org/dflib/jjava/distro/NotebookInitializer.java

@@ -29,6 +29,6 @@ public class NotebookInitializer implements Extension {
 
     @Override
     public void install(BaseKernel kernel) {
-        kernel.eval(STARTUP_SCRIPT);
+        kernel.evalBuilder(STARTUP_SCRIPT).resolveMagics().eval();
     }
 }

jjava-jupyter/src/main/java/org/dflib/jjava/jupyter/kernel/BaseKernel.java

@@ -198,41 +198,33 @@ public void display(DisplayData data) {
     }
 
     /**
-     * Same as {@link #eval(String)}, but not applying the renderer to evaluation result.
+     * @deprecated unused, replaced with {@link #evalBuilder(String)} pipeline.
      */
-    public abstract Object evalRaw(String source);
+    @Deprecated(forRemoval = true)
+    public DisplayData eval(String source) {
+        return evalBuilder(source).resolveMagics().renderResults().eval();
+    }
 
     /**
-     * Evaluates a code expression in the kernel's language environment and returns the result
-     * as display data. This is the core evaluation method called when executing code cells
-     * in a Jupyter notebook.
-     *
-     * <p>The implementation should:
-     * <ul>
-     *   <li>Parse and evaluate the provided expression string</li>
-     *   <li>Convert the evaluation result into appropriate display data formats</li>
-     *   <li>Handle any language-specific evaluation context/scope</li>
-     * </ul>
-     *
-     * <p>The returned {@link DisplayData} can contain multiple representations of the result
-     * (e.g. text/plain, text/html, image/png) to allow rich display in the notebook.
-     * Return null if the expression produces no displayable result.
-     *
-     * @param expr The code expression to evaluate as received from the Jupyter frontend
-     * @return A {@link DisplayData} object containing the evaluation result in one or more
-     * MIME formats, or null if there is no displayable result
+     * @deprecated unused, replaced with {@link #evalBuilder(String)} pipeline.
      */
-    public DisplayData eval(String expr) {
-        Object result = evalRaw(expr);
-        if (result == null) {
-            return null;
-        }
+    @Deprecated(forRemoval = true)
+    public Object evalRaw(String source) {
+        return evalBuilder(source).resolveMagics().eval();
+    }
 
-        return result instanceof DisplayData
-                ? (DisplayData) result
-                : getRenderer().render(result);
+    /**
+     * Creates and returns a builder for an evaluation pipeline.
+     */
+    public <T> SimpleEvalBuilder<T> evalBuilder(String source) {
+        return new SimpleEvalBuilder<>(this, source);
     }
 
+    /**
+     * Evaluates the source code in a way appropriate for a given kernel subclass.
+     */
+    protected abstract Object doEval(String source);
+
     /**
      * Inspect the code to get things such as documentation for a function. This is
      * triggered by {@code shift-tab} in the Jupyter notebook which opens a tooltip displaying
@@ -360,21 +352,7 @@ public void interrupt() {
         // no-op
     }
 
-    /**
-     * Formats an error into a human friendly format. The default implementation prints
-     * the stack trace as written by {@link Throwable#printStackTrace()} with a dividing
-     * separator as a prefix.
-     * <p>
-     * Subclasses may override this method write better messages for specific errors but
-     * may choose to still use this to display the stack trace. In this case it is recommended
-     * to add the output of this call to the end of the output list.
-     *
-     * @param e the error to format
-     * @return a list of lines that make up the formatted error. This format should
-     * not include strings with newlines but rather separate strings each to go on a
-     * new line.
-     */
-    public List<String> formatError(Throwable e) {
+    protected List<String> formatError(Throwable e) {
         List<String> lines = new ArrayList<>();
         lines.add(this.errorStyler.secondary("---------------------------------------------------------------------------"));
 
@@ -389,12 +367,6 @@ public List<String> formatError(Throwable e) {
         return lines;
     }
 
-    /*
-     * ===================================
-     * | Default handler implementations |
-     * ===================================
-     */
-
     public void becomeHandlerForConnection(JupyterConnection connection) {
         connection.setHandler(MessageType.EXECUTE_REQUEST, this::handleExecuteRequest);
         connection.setHandler(MessageType.INSPECT_REQUEST, this::handleInspectRequest);
@@ -446,7 +418,7 @@ protected synchronized void handleExecuteRequest(ShellReplyEnvironment env, Mess
         this.io.setJupyterInEnabled(request.isStdinEnabled());
 
         try {
-            DisplayData out = eval(request.getCode());
+            DisplayData out = evalBuilder(request.getCode()).resolveMagics().renderResults().eval();
 
             if (out != null) {
                 PublishExecuteResult result = new PublishExecuteResult(count, out);

jjava-jupyter/src/main/java/org/dflib/jjava/jupyter/kernel/BaseNotebookStatics.java

@@ -16,8 +16,8 @@ public static void printf(String format, Object... args) {
         System.out.printf(format, args);
     }
 
-    public static Object eval(String expr) {
-        return BaseKernel.notebookKernel().evalRaw(expr);
+    public static Object eval(String source) {
+        return BaseKernel.notebookKernel().evalBuilder(source).resolveMagics().eval();
     }
 
     public static <T> T lineMagic(String name, List<String> args) {

jjava-jupyter/src/main/java/org/dflib/jjava/jupyter/kernel/EvalBuilder.java

@@ -0,0 +1,12 @@
+package org.dflib.jjava.jupyter.kernel;
+
+import org.dflib.jjava.jupyter.kernel.display.DisplayData;
+
+public interface EvalBuilder<T> {
+
+    EvalBuilder<T> resolveMagics();
+
+    EvalBuilder<DisplayData> renderResults();
+
+    T eval();
+}

jjava-jupyter/src/main/java/org/dflib/jjava/jupyter/kernel/RenderedEvalBuilder.java

@@ -0,0 +1,37 @@
+package org.dflib.jjava.jupyter.kernel;
+
+import org.dflib.jjava.jupyter.kernel.display.DisplayData;
+
+public class RenderedEvalBuilder implements EvalBuilder<DisplayData> {
+
+    private final BaseKernel kernel;
+    private final EvalBuilder<?> delegate;
+
+    protected RenderedEvalBuilder(BaseKernel kernel, EvalBuilder<?> delegate) {
+        this.kernel = kernel;
+        this.delegate = delegate;
+    }
+
+    @Override
+    public EvalBuilder<DisplayData> renderResults() {
+        return this;
+    }
+
+    @Override
+    public RenderedEvalBuilder resolveMagics() {
+        return new RenderedEvalBuilder(kernel, delegate.resolveMagics());
+    }
+
+    @Override
+    public DisplayData eval() {
+        Object o = delegate.eval();
+
+        if (o == null) {
+            return null;
+        }
+
+        return o instanceof DisplayData
+                ? (DisplayData) o
+                : kernel.getRenderer().render(o);
+    }
+}

jjava-jupyter/src/main/java/org/dflib/jjava/jupyter/kernel/SimpleEvalBuilder.java

@@ -0,0 +1,29 @@
+package org.dflib.jjava.jupyter.kernel;
+
+import org.dflib.jjava.jupyter.kernel.display.DisplayData;
+
+public class SimpleEvalBuilder<T> implements EvalBuilder<T> {
+
+    private final BaseKernel kernel;
+    private final String source;
+
+    protected SimpleEvalBuilder(BaseKernel kernel, String source) {
+        this.kernel = kernel;
+        this.source = source;
+    }
+
+    @Override
+    public EvalBuilder<T> resolveMagics() {
+        return new SimpleEvalBuilder<>(kernel, kernel.getMagicsResolver().resolve(source));
+    }
+
+    @Override
+    public EvalBuilder<DisplayData> renderResults() {
+        return new RenderedEvalBuilder(kernel, this);
+    }
+
+    @Override
+    public T eval() {
+        return (T) kernel.doEval(source);
+    }
+}

jjava-kernel/src/main/java/org/dflib/jjava/kernel/JavaKernel.java

@@ -115,7 +115,7 @@ public void addToClasspath(String classpath) {
     }
 
     @Override
-    public List<String> formatError(Throwable e) {
+    protected List<String> formatError(Throwable e) {
         if (e instanceof CompilationException) {
             return formatCompilationException((CompilationException) e);
         } else if (e instanceof IncompleteSourceException) {
@@ -226,12 +226,9 @@ private List<String> formatEvaluationInterruptedException(EvaluationInterruptedE
         return fmt;
     }
 
-    /**
-     * Same as {@link #eval(String)}, but not applying the renderer to evaluation result.
-     */
     @Override
-    public Object evalRaw(String source) {
-        return evaluator.eval(magicsResolver.resolve(source));
+    protected Object doEval(String source) {
+        return evaluator.eval(source);
     }
 
     @Override

jjava-kernel/src/main/java/org/dflib/jjava/kernel/magics/LoadCodeMagic.java

@@ -49,11 +49,13 @@ public Void eval(JavaKernel kernel, List<String> args) throws Exception {
             Path scriptPath = sourcePath.resolveSibling(file + extension);
             if (Files.isRegularFile(scriptPath)) {
 
+                // TODO: return rendered "eval" results to the caller would make sense here
+
                 if (scriptPath.getFileName().endsWith(NOTEBOOK_EXTENSION)) {
                     execNotebook(kernel, scriptPath);
                 } else {
-                    String sourceContents = Files.readString(scriptPath);
-                    kernel.eval(sourceContents);
+                    String source = Files.readString(scriptPath);
+                    kernel.evalBuilder(source).resolveMagics().eval();
                 }
                 return null;
             }
@@ -118,7 +120,7 @@ private void execNotebook(JavaKernel kernel, Path notebookPath) throws Exception
 
                     // Found a code cell!
                     if (isCode != null && isCode) {
-                        kernel.eval(source);
+                        kernel.evalBuilder(source).resolveMagics().eval();
                     }
                 }
                 reader.endArray();