Handle RenderDirective in annotation converters

Author: HT154

pkl-core/src/main/java/org/pkl/core/runtime/VmPklBinaryEncoder.java

@@ -258,6 +258,11 @@ protected void visitProperty(Identifier name, Object value, boolean isFirst) {
     visit(value);
   }
 
+  @Override
+  protected void visitPropertyRenderDirective(VmTyped value, boolean isFirst) {
+    visitRenderDirective(value);
+  }
+
   @Override
   public void visitClass(VmClass value) {
     try {

pkl-core/src/main/java/org/pkl/core/runtime/VmValueConverter.java

@@ -85,6 +85,7 @@ public String toString() {
 
   T convertFunction(VmFunction value, Iterable<Object> path);
 
+  /** Returns with an empty identifier if the second value is a RenderDirective */
   Pair<Identifier, T> convertProperty(ClassProperty property, Object value, Iterable<Object> path);
 
   default T convert(Object value, Iterable<Object> path) {

pkl-core/src/main/java/org/pkl/core/stdlib/AbstractRenderer.java

@@ -163,6 +163,9 @@ public void visit(Object value) {
   /** Visits a property of a {@link VmDynamic} or {@link VmTyped}. */
   protected abstract void visitProperty(Identifier name, Object value, boolean isFirst);
 
+  /** Perform logic for rendering a render directive in place of a property */
+  protected abstract void visitPropertyRenderDirective(VmTyped value, boolean isFirst);
+
   protected abstract void endDynamic(VmDynamic value, boolean isEmpty);
 
   protected abstract void endTyped(VmTyped value, boolean isEmpty);
@@ -346,9 +349,14 @@ private void doVisitProperty(
       name = propVal.getFirst();
       value = propVal.getSecond();
     }
-    var convertedValue = converter.convert(value, currPath);
-    if (!(skipNullProperties && convertedValue instanceof VmNull)) {
-      visitProperty(name, convertedValue, isFirst.getAndSetFalse());
+    if (name.toString().isEmpty()) {
+      assert isRenderDirective(value);
+      visitPropertyRenderDirective((VmTyped) value, isFirst.getAndSetFalse());
+    } else {
+      var convertedValue = converter.convert(value, currPath);
+      if (!(skipNullProperties && convertedValue instanceof VmNull)) {
+        visitProperty(name, convertedValue, isFirst.getAndSetFalse());
+      }
     }
     currPath.pop();
     currSourceSection = prevSourceSection;

pkl-core/src/main/java/org/pkl/core/stdlib/PklConverter.java

@@ -23,7 +23,7 @@
 
 public final class PklConverter implements VmValueConverter<Object> {
   private interface AnnotationConverter {
-    VmPair convert(String property, VmTyped annotation, Object value);
+    Object convert(String property, VmTyped annotation, Object value);
   }
 
   private final Map<VmClass, VmFunction> typeConverters;
@@ -208,9 +208,10 @@ public Pair<Identifier, Object> convertProperty(
       if (converter == null) {
         continue;
       }
-      var nameVal = converter.convert(name.toString(), annotation, value);
-      name = Identifier.get((String) nameVal.getFirst());
-      value = nameVal.getSecond();
+      var converted = converter.convert(name.toString(), annotation, value);
+      return converted instanceof VmPair vmPair
+          ? Pair.of(Identifier.get((String) vmPair.getFirst()), vmPair.getSecond())
+          : Pair.of(Identifier.get(""), converted); // RenderDirective
     }
 
     return Pair.of(name, value);
@@ -237,8 +238,7 @@ private Map<VmClass, AnnotationConverter> createAnnotationConverters(
           assert value != null; // forced in ctor
           result.put(
               (VmClass) key,
-              (name, annotation, val) ->
-                  (VmPair) ((VmFunction) value).apply(annotation, name, val));
+              (name, annotation, val) -> ((VmFunction) value).apply(annotation, name, val));
           return true;
         });
 

pkl-core/src/main/java/org/pkl/core/stdlib/base/JsonRendererNodes.java

@@ -233,6 +233,13 @@ protected void visitProperty(Identifier name, Object value, boolean isFirst) {
       visit(value);
     }
 
+    @Override
+    protected void visitPropertyRenderDirective(VmTyped value, boolean isFirst) {
+      if (!isFirst) builder.append(',');
+      startNewLine();
+      visitRenderDirective(value);
+    }
+
     @Override
     protected void endDynamic(VmDynamic value, boolean isEmpty) {
       if (value.hasElements()) {

pkl-core/src/main/java/org/pkl/core/stdlib/base/PListRendererNodes.java

@@ -279,6 +279,16 @@ protected void visitProperty(Identifier name, Object value, boolean isFirst) {
       builder.append(LINE_BREAK);
     }
 
+    @Override
+    protected void visitPropertyRenderDirective(VmTyped value, boolean isFirst) {
+      if (isFirst) {
+        builder.append("<dict>").append(LINE_BREAK);
+      }
+      builder.append(currIndent);
+      visitRenderDirective(value);
+      builder.append(LINE_BREAK);
+    }
+
     @Override
     protected void endDynamic(VmDynamic value, boolean isEmpty) {
       if (value.hasElements()) {

pkl-core/src/main/java/org/pkl/core/stdlib/base/PcfRenderer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -279,6 +279,15 @@ protected void visitProperty(Identifier name, Object value, boolean isFirst) {
     visit(value);
   }
 
+  @Override
+  protected void visitPropertyRenderDirective(VmTyped value, boolean isFirst) {
+    if (!builder.isEmpty()) {
+      builder.append('\n');
+      builder.append(currIndent);
+    }
+    visitRenderDirective(value);
+  }
+
   @Override
   protected void endDynamic(VmDynamic value, boolean isEmpty) {
     endObject(value, isEmpty);

pkl-core/src/main/java/org/pkl/core/stdlib/base/PropertiesRendererNodes.java

@@ -231,6 +231,14 @@ protected void visitProperty(Identifier name, Object value, boolean isFirst) {
       visitKeyedValue(value);
     }
 
+    @Override
+    protected void visitPropertyRenderDirective(VmTyped value, boolean isFirst) {
+      builder.append(VmUtils.readTextProperty(value));
+      if (isDocument) {
+        writeLineBreak();
+      }
+    }
+
     @Override
     protected void endDynamic(VmDynamic value, boolean isEmpty) {}
 

pkl-core/src/main/java/org/pkl/core/stdlib/base/YamlRendererNodes.java

@@ -334,6 +334,14 @@ protected void visitProperty(Identifier name, Object value, boolean isFirst) {
       visit(value);
     }
 
+    @Override
+    protected void visitPropertyRenderDirective(VmTyped value, boolean isFirst) {
+      if (!isFirst) {
+        startNewLine();
+      }
+      visitRenderDirective(value);
+    }
+
     @Override
     protected void endDynamic(VmDynamic value, boolean isEmpty) {
       if (value.hasElements()) {

pkl-core/src/main/java/org/pkl/core/stdlib/jsonnet/RendererNodes.java

@@ -309,6 +309,15 @@ protected void visitProperty(Identifier name, Object value, boolean isFirst) {
       visit(value);
     }
 
+    @Override
+    protected void visitPropertyRenderDirective(VmTyped value, boolean isFirst) {
+      if (!isFirst) {
+        builder.append(',');
+      }
+      builder.append(memberSeparator).append(currIndent);
+      visitRenderDirective(value);
+    }
+
     @Override
     protected void visitElement(long index, Object value, boolean isFirst) {
       if (!isFirst) {