Add pkl:syntax module

pkl-core/pkl-core.gradle.kts

@@ -48,6 +48,7 @@ dependencies {
   compileOnly(projects.pklExecutor)
 
   implementation(projects.pklParser)
+  implementation(projects.pklFormatter)
   implementation(libs.msgpack)
   implementation(libs.truffleApi)
   implementation(libs.graalSdk)

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

@@ -113,6 +113,8 @@ public synchronized VmTyped getOrLoad(
         case "settings":
           // always needed if ~/.pkl/settings.pkl is present
           return SettingsModule.getModule();
+        case "syntax":
+          return SyntaxModule.getModule();
         case "test":
           return TestModule.getModule();
         case "xml":

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

@@ -0,0 +1,61 @@
+/*
+ * Copyright © 2025-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.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.pkl.core.runtime;
+
+import com.oracle.truffle.api.CompilerDirectives;
+import java.net.URI;
+
+public final class SyntaxModule extends StdLibModule {
+  private static final VmTyped instance = VmUtils.createEmptyModule();
+
+  static {
+    loadModule(URI.create("pkl:syntax"), instance);
+  }
+
+  public static VmTyped getModule() {
+    return instance;
+  }
+
+  public static VmClass getNodeClass() {
+    return NodeClass.instance;
+  }
+
+  public static VmClass getSpanClass() {
+    return SpanClass.instance;
+  }
+
+  public static VmClass getParserErrorClass() {
+    return ParserErrorClass.instance;
+  }
+
+  private static final class NodeClass {
+    static final VmClass instance = loadClass("Node");
+  }
+
+  private static final class SpanClass {
+    static final VmClass instance = loadClass("Span");
+  }
+
+  private static final class ParserErrorClass {
+    static final VmClass instance = loadClass("ParserError");
+  }
+
+  @CompilerDirectives.TruffleBoundary
+  private static VmClass loadClass(String className) {
+    var theModule = getModule();
+    return (VmClass) VmUtils.readMember(theModule, Identifier.get(className));
+  }
+}

pkl-core/src/main/java/org/pkl/core/stdlib/syntax/SyntaxNodes.java

@@ -0,0 +1,187 @@
+/*
+ * Copyright © 2025-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.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.pkl.core.stdlib.syntax;
+
+import com.oracle.truffle.api.CompilerDirectives.TruffleBoundary;
+import com.oracle.truffle.api.dsl.Specialization;
+import java.util.ArrayList;
+import java.util.Locale;
+import org.jspecify.annotations.Nullable;
+import org.pkl.core.runtime.Identifier;
+import org.pkl.core.runtime.SyntaxModule;
+import org.pkl.core.runtime.VmList;
+import org.pkl.core.runtime.VmNull;
+import org.pkl.core.runtime.VmTyped;
+import org.pkl.core.runtime.VmUtils;
+import org.pkl.core.stdlib.ExternalMethod1Node;
+import org.pkl.core.stdlib.ExternalMethod2Node;
+import org.pkl.core.stdlib.VmObjectFactory;
+import org.pkl.formatter.Formatter;
+import org.pkl.formatter.GrammarVersion;
+import org.pkl.parser.GenericParser;
+import org.pkl.parser.GenericParserError;
+import org.pkl.parser.syntax.generic.FullSpan;
+import org.pkl.parser.syntax.generic.Node;
+import org.pkl.parser.syntax.generic.NodeType;
+
+public final class SyntaxNodes {
+  private SyntaxNodes() {}
+
+  private static final Identifier TYPE_ID = Identifier.get("type");
+  private static final Identifier CHILDREN_ID = Identifier.get("children");
+  private static final Identifier SPAN_ID = Identifier.get("span");
+  private static final Identifier LINE_START_ID = Identifier.get("lineStart");
+  private static final Identifier COL_START_ID = Identifier.get("colStart");
+  private static final Identifier LINE_END_ID = Identifier.get("lineEnd");
+  private static final Identifier COL_END_ID = Identifier.get("colEnd");
+  private static final char[] EMPTY_SOURCE = new char[0];
+
+  /** Extra storage backing a Pkl {@code Node} instance. */
+  static final class NodeData {
+    final Node node;
+    final char[] source;
+    @Nullable VmTyped parentVm;
+    VmList childrenVm;
+    VmTyped spanVm;
+
+    NodeData(Node node, char[] source, VmList childrenVm, VmTyped spanVm) {
+      this.node = node;
+      this.source = source;
+      this.childrenVm = childrenVm;
+      this.spanVm = spanVm;
+    }
+  }
+
+  /** Extra storage backing a Pkl {@code ParserError} instance. */
+  static final class ErrorData {
+    final String text;
+    final VmTyped spanVm;
+
+    ErrorData(String text, VmTyped spanVm) {
+      this.text = text;
+      this.spanVm = spanVm;
+    }
+  }
+
+  private static final VmObjectFactory<FullSpan> spanFactory =
+      new VmObjectFactory<FullSpan>(SyntaxModule::getSpanClass)
+          .addIntProperty("lineStart", FullSpan::lineBegin)
+          .addIntProperty("colStart", FullSpan::colBegin)
+          .addIntProperty("lineEnd", FullSpan::lineEnd)
+          .addIntProperty("colEnd", FullSpan::colEnd);
+
+  private static final VmObjectFactory<NodeData> nodeFactory =
+      new VmObjectFactory<NodeData>(SyntaxModule::getNodeClass)
+          .addStringProperty("type", nd -> nd.node.type.name().toLowerCase(Locale.ROOT))
+          .addListProperty("children", nd -> nd.childrenVm)
+          .addProperty("parent", nd -> VmNull.lift(nd.parentVm))
+          .addProperty(
+              "text",
+              nd -> nd.node.children.isEmpty() ? nd.node.text(nd.source) : VmNull.withoutDefault())
+          .addTypedProperty("span", nd -> nd.spanVm);
+
+  private static final VmObjectFactory<ErrorData> parserErrorFactory =
+      new VmObjectFactory<ErrorData>(SyntaxModule::getParserErrorClass)
+          .addStringProperty("text", ed -> ed.text)
+          .addTypedProperty("span", ed -> ed.spanVm);
+
+  public abstract static class parseNodes extends ExternalMethod1Node {
+    @Specialization
+    @TruffleBoundary
+    protected Object eval(VmTyped self, String source) {
+      var sourceChars = source.toCharArray();
+
+      try {
+        var parser = new GenericParser();
+        var root = parser.parseModule(source);
+        return convertNode(root, sourceChars);
+      } catch (GenericParserError e) {
+        var errorSpanVm = spanFactory.create(e.getSpan());
+        var text = e.getMessage() != null ? e.getMessage() : "Parse error";
+        return parserErrorFactory.create(new ErrorData(text, errorSpanVm));
+      }
+    }
+
+    private static VmTyped convertNode(Node genericNode, char[] sourceChars) {
+      // convert children recursively
+      var childrenList = new ArrayList<VmTyped>(genericNode.children.size());
+      for (var child : genericNode.children) {
+        childrenList.add(convertNode(child, sourceChars));
+      }
+
+      var childrenVm = VmList.create(childrenList.toArray());
+      var spanVm = spanFactory.create(genericNode.span);
+      var data = new NodeData(genericNode, sourceChars, childrenVm, spanVm);
+
+      var result = nodeFactory.create(data);
+
+      // set parent back-reference on each child
+      for (var childVm : childrenList) {
+        var childData = (NodeData) childVm.getExtraStorage();
+        childData.parentVm = result;
+      }
+
+      return result;
+    }
+  }
+
+  public abstract static class formatToString extends ExternalMethod2Node {
+    @Specialization
+    @TruffleBoundary
+    protected String eval(VmTyped self, VmTyped nodeVm, String grammarVersion) {
+      var node = convertVmToNode(nodeVm);
+      return new Formatter(GrammarVersion.valueOf(grammarVersion)).format(node);
+    }
+  }
+
+  private static Node convertVmToNode(VmTyped nodeVm) {
+    var typeStr = (String) VmUtils.readMember(nodeVm, TYPE_ID);
+    var nodeType = NodeType.valueOf(typeStr.toUpperCase(Locale.ROOT));
+
+    var childrenVm = (VmList) VmUtils.readMember(nodeVm, CHILDREN_ID);
+    var children = new ArrayList<Node>(childrenVm.getLength());
+    for (var i = 0; i < childrenVm.getLength(); i++) {
+      children.add(convertVmToNode((VmTyped) childrenVm.get(i)));
+    }
+
+    var spanVm = (VmTyped) VmUtils.readMember(nodeVm, SPAN_ID);
+    var lineStart = ((Long) VmUtils.readMember(spanVm, LINE_START_ID)).intValue();
+    var colStart = ((Long) VmUtils.readMember(spanVm, COL_START_ID)).intValue();
+    var lineEnd = ((Long) VmUtils.readMember(spanVm, LINE_END_ID)).intValue();
+    var colEnd = ((Long) VmUtils.readMember(spanVm, COL_END_ID)).intValue();
+    var span = new FullSpan(0, 0, lineStart, colStart, lineEnd, colEnd);
+
+    Node node;
+    if (children.isEmpty()) {
+      node = new Node(nodeType, span);
+    } else {
+      node = new Node(nodeType, span, children);
+    }
+
+    var textObj = VmUtils.readMember(nodeVm, Identifier.TEXT);
+    if (textObj instanceof String text) {
+      node.setText(text);
+    } else if (nodeType == NodeType.STRING_CHARS) {
+      var sb = new StringBuilder();
+      for (var child : children) {
+        sb.append(child.text(EMPTY_SOURCE));
+      }
+      node.setText(sb.toString());
+    }
+
+    return node;
+  }
+}

pkl-core/src/main/java/org/pkl/core/stdlib/syntax/package-info.java

@@ -0,0 +1,4 @@
+@NullMarked
+package org.pkl.core.stdlib.syntax;
+
+import org.jspecify.annotations.NullMarked;