Implement Reference<T>

Author: HT154

docs/modules/ROOT/partials/component-attributes.adoc

@@ -148,6 +148,8 @@ endif::[]
 :uri-stdlib-Function4: {uri-stdlib-baseModule}/Function4
 :uri-stdlib-Function5: {uri-stdlib-baseModule}/Function5
 :uri-stdlib-Bytes: {uri-stdlib-baseModule}/Bytes
+:uri-stdlib-Reference: {uri-stdlib-baseModule}/Reference
+:uri-stdlib-ReferenceAccess: {uri-stdlib-baseModule}/ReferenceAccess
 :uri-stdlib-Resource: {uri-stdlib-baseModule}/Resource
 :uri-stdlib-outputFiles: {uri-stdlib-baseModule}/ModuleOutput#files
 :uri-stdlib-FileOutput: {uri-stdlib-baseModule}/FileOutput

docs/modules/bindings-specification/pages/binary-encoding.adoc

@@ -187,6 +187,24 @@ The array's length is the number of slots that are filled. For example, xref:{ur
 |
 |
 |
+
+|link:{uri-stdlib-Reference}[Reference]
+|`0x20`
+|`<value>`
+|Root value
+|link:{uri-messagepack-array}[array]
+|Array of link:{uri-stdlib-ReferenceAccess}[property access] values
+|
+|
+
+|link:{uri-stdlib-ReferenceAccess}[ReferenceAccess]
+|`0x21`
+|link:{uri-messagepack-str}[str] (when a property access) or link:{uri-messagepack-str}[nil] (when a subscript access)
+|Property name
+|`<value>` or link:{uri-messagepack-str}[nil] (when a property access)
+|Key value
+|
+|
 |===
 
 [[type-name-encoding]]

pkl-core/src/main/java/org/pkl/core/PClass.java

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 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.
@@ -27,6 +27,7 @@ public final class PClass extends Member implements Value {
   private final List<TypeParameter> typeParameters;
   private final Map<String, Property> properties;
   private final Map<String, Method> methods;
+  private final @Nullable PClass moduleClass;
 
   private @Nullable PType supertype;
   private @Nullable PClass superclass;
@@ -42,12 +43,14 @@ public PClass(
       PClassInfo<?> classInfo,
       List<TypeParameter> typeParameters,
       Map<String, Property> properties,
-      Map<String, Method> methods) {
+      Map<String, Method> methods,
+      @Nullable PClass moduleClass) {
     super(docComment, sourceLocation, modifiers, annotations, classInfo.getSimpleName());
     this.classInfo = classInfo;
     this.typeParameters = typeParameters;
     this.properties = properties;
     this.methods = methods;
+    this.moduleClass = moduleClass;
   }
 
   public void initSupertype(PType supertype, PClass superclass) {
@@ -119,6 +122,11 @@ public Map<String, Method> getAllMethods() {
     return allMethods;
   }
 
+  /** Returns the class's containing module's class, or this class if it is a module class. */
+  public PClass getModuleClass() {
+    return moduleClass != null ? moduleClass : this;
+  }
+
   @Override
   public void accept(ValueVisitor visitor) {
     visitor.visitClass(this);
@@ -138,6 +146,10 @@ public String toString() {
     return getDisplayName();
   }
 
+  public boolean isSubclassOf(PClass other) {
+    return this == other || getSuperclass() != null && getSuperclass().isSubclassOf(other);
+  }
+
   public abstract static class ClassMember extends Member {
     @Serial private static final long serialVersionUID = 0L;
 

pkl-core/src/main/java/org/pkl/core/PType.java

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 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.
@@ -18,6 +18,7 @@
 import java.io.Serial;
 import java.io.Serializable;
 import java.util.*;
+import java.util.stream.Collectors;
 
 /** A Pkl type as used in type annotations. */
 public abstract class PType implements Serializable {
@@ -27,18 +28,33 @@ public abstract class PType implements Serializable {
   public static final PType UNKNOWN =
       new PType() {
         @Serial private static final long serialVersionUID = 0L;
+
+        @Override
+        public String toString() {
+          return "unknown";
+        }
       };
 
   /** The bottom type. */
   public static final PType NOTHING =
       new PType() {
         @Serial private static final long serialVersionUID = 0L;
+
+        @Override
+        public String toString() {
+          return "nothing";
+        }
       };
 
   /** The type of the enclosing module. */
   public static final PType MODULE =
       new PType() {
         @Serial private static final long serialVersionUID = 0L;
+
+        @Override
+        public String toString() {
+          return "module";
+        }
       };
 
   private PType() {}
@@ -59,6 +75,10 @@ public StringLiteral(String literal) {
     public String getLiteral() {
       return literal;
     }
+
+    public String toString() {
+      return ValueFormatter.basic().formatStringValue(literal, "");
+    }
   }
 
   public static final class Class extends PType {
@@ -92,6 +112,18 @@ public PClass getPClass() {
     public List<PType> getTypeArguments() {
       return typeArguments;
     }
+
+    @Override
+    public String toString() {
+      var result = pClass.getDisplayName();
+      if (!typeArguments.isEmpty()) {
+        result +=
+            "<"
+                + typeArguments.stream().map(Object::toString).collect(Collectors.joining(", "))
+                + ">";
+      }
+      return result;
+    }
   }
 
   public static final class Nullable extends PType {
@@ -106,6 +138,13 @@ public Nullable(PType baseType) {
     public PType getBaseType() {
       return baseType;
     }
+
+    @Override
+    public String toString() {
+      return baseType instanceof Function || baseType instanceof Union
+          ? "(" + baseType + ")?"
+          : baseType + "?";
+    }
   }
 
   public static final class Constrained extends PType {
@@ -126,6 +165,16 @@ public PType getBaseType() {
     public List<String> getConstraints() {
       return constraints;
     }
+
+    @Override
+    public String toString() {
+      return (baseType instanceof Function || baseType instanceof Union
+              ? "(" + baseType + ")"
+              : baseType)
+          + "("
+          + String.join(", ", constraints)
+          + ")";
+    }
   }
 
   public static final class Alias extends PType {
@@ -161,6 +210,18 @@ public List<PType> getTypeArguments() {
     public PType getAliasedType() {
       return aliasedType;
     }
+
+    @Override
+    public String toString() {
+      var result = typeAlias.getDisplayName();
+      if (!typeArguments.isEmpty()) {
+        result +=
+            "<"
+                + typeArguments.stream().map(Object::toString).collect(Collectors.joining(", "))
+                + ">";
+      }
+      return result;
+    }
   }
 
   public static final class Function extends PType {
@@ -181,6 +242,14 @@ public List<PType> getParameterTypes() {
     public PType getReturnType() {
       return returnType;
     }
+
+    @Override
+    public String toString() {
+      return "("
+          + parameterTypes.stream().map(Object::toString).collect(Collectors.joining(", "))
+          + ") -> "
+          + returnType;
+    }
   }
 
   public static final class Union extends PType {
@@ -195,6 +264,11 @@ public Union(List<PType> elementTypes) {
     public List<PType> getElementTypes() {
       return elementTypes;
     }
+
+    @Override
+    public String toString() {
+      return elementTypes.stream().map(Object::toString).collect(Collectors.joining(" | "));
+    }
   }
 
   public static final class TypeVariable extends PType {
@@ -213,5 +287,10 @@ public String getName() {
     public TypeParameter getTypeParameter() {
       return typeParameter;
     }
+
+    @Override
+    public String toString() {
+      return typeParameter.getName();
+    }
   }
 }

pkl-core/src/main/java/org/pkl/core/TypeAlias.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.
@@ -28,6 +28,7 @@ public final class TypeAlias extends Member implements Value {
   private final String moduleName;
   private final String qualifiedName;
   private final List<TypeParameter> typeParameters;
+  private final PClass moduleClass;
 
   @LateInit private PType aliasedType;
 
@@ -39,11 +40,13 @@ public TypeAlias(
       String simpleName,
       String moduleName,
       String qualifiedName,
-      List<TypeParameter> typeParameters) {
+      List<TypeParameter> typeParameters,
+      PClass moduleClass) {
     super(docComment, sourceLocation, modifiers, annotations, simpleName);
     this.moduleName = moduleName;
     this.qualifiedName = qualifiedName;
     this.typeParameters = typeParameters;
+    this.moduleClass = moduleClass;
   }
 
   public void initAliasedType(PType type) {
@@ -78,6 +81,10 @@ public List<TypeParameter> getTypeParameters() {
     return typeParameters;
   }
 
+  public PClass getModuleClass() {
+    return moduleClass;
+  }
+
   /** Returns the type that this type alias stands for. */
   public PType getAliasedType() {
     assert aliasedType != null;

pkl-core/src/main/java/org/pkl/core/ast/expression/binary/SubscriptNode.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.
@@ -98,6 +98,20 @@ protected Object eval(
     return readMember(dynamic, key, callNode);
   }
 
+  @Specialization
+  protected VmReference eval(VmReference reference, Object key) {
+    var result = reference.withSubscriptAccess(key);
+    if (result != null) return result;
+
+    CompilerDirectives.transferToInterpreter();
+    throw exceptionBuilder()
+        .evalError(
+            "operatorNotDefined2", getShortName(), reference.exportType(), VmUtils.getClass(key))
+        .withProgramValue("Left operand", reference)
+        .withProgramValue("Right operand", key)
+        .build();
+  }
+
   @Specialization
   protected long eval(VmBytes receiver, long index) {
     if (index < 0 || index >= receiver.getLength()) {

pkl-core/src/main/java/org/pkl/core/ast/expression/member/ReadPropertyNode.java

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 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.
@@ -61,6 +61,18 @@ protected ReadPropertyNode(SourceSection sourceSection, Identifier propertyName)
     this(sourceSection, propertyName, MemberLookupMode.EXPLICIT_RECEIVER, false);
   }
 
+  @Specialization
+  protected VmReference evalReference(VmReference receiver) {
+    assert lookupMode == MemberLookupMode.EXPLICIT_RECEIVER;
+    var result = receiver.withPropertyAccess(propertyName);
+    if (result != null) return result;
+
+    CompilerDirectives.transferToInterpreter();
+    throw exceptionBuilder()
+        .evalError("cannotFindPropertyInReference", propertyName, receiver.exportType())
+        .build();
+  }
+
   // This method effectively covers `VmObject receiver` but is implemented in a more
   // efficient way. See:
   // https://www.graalvm.org/22.0/graalvm-as-a-platform/language-implementation-framework/TruffleLibraries/#strategy-2-java-interfaces