Add user generic methods (#1849)

stdlib/ref.pkl

@@ -31,25 +31,16 @@
 @Since { version = "0.32.0" }
 module pkl.ref
 
-/// Creates a deferred [Reference] to a value of type [`class`] in the given [domain] and [data].
-///
-/// References may only be constructed for single, non-generic class types.
-/// To create a reference to other types (generic classes, union, nullable, constrained,
-/// typealiases, etc.), use a wrapper class with a property of the desired type.
+/// Creates a deferred [Reference] to a value of type [Type] in the given [domain] and [data].
 ///
 /// Example:
 /// ```
-/// myReference: Reference<MyDomain, Listing<String>> = Reference(domain, Holder, data).$
-///
-/// class Holder {
-///   $: Listing<String>
-/// }
+/// myReference: Reference<MyDomain, Listing<String>> = Reference::<MyDomain, Listing<String>>(domain, data)
 /// ```
-external const function Reference<D, T>(
-  domain: D(this is Domain),
-  `class`: Class<T>,
+external const function Reference<Domain, Type>(
+  domain: Domain(this is AbstractDomain),
   data: Any,
-): Reference<D, T>
+): Reference<Domain, Type>
 
 /// References are an advanced API design tool that enables library authors to express
 /// domain-specific values, whose actual underlying values are not known to Pkl during evaluation.
@@ -116,14 +107,14 @@ external const function Reference<D, T>(
 ///
 /// ## Domain
 ///
-/// The [Domain] parameter identifies the system that this reference exists inside.
+/// The domain identifies the system that this reference exists inside.
 /// Additionally, it defines how references should be rendered when Pkl produces textual output.
 ///
 /// Example:
 /// ```
 /// import "pkl:ref"
 ///
-/// class MyDomain extends ref.Domain {
+/// class MyDomain extends ref.AbstractDomain {
 ///   // Define how this domain renders references to strings:
 ///   function renderReference(reference: ref.Reference<MyDomain, Any>): String =
 ///     reference.getData().toString()
@@ -143,7 +134,7 @@ external const function Reference<D, T>(
 /// ```
 /// import "pkl:ref"
 ///
-/// class Foo extends ref.Domain {
+/// class Foo extends ref.AbstractDomain {
 ///   function renderReference(reference: ref.Reference<Foo, Any>) =
 ///     "{{ "
 ///     + reference.getData().toString()
@@ -162,7 +153,7 @@ external const function Reference<D, T>(
 ///   properties: Mapping<String, String>
 /// }
 ///
-/// local outputs: FooReference<Outputs> = ref.Reference(new Foo {}, Outputs, "outputs")
+/// local outputs: FooReference<Outputs> = ref.Reference::<Foo, Outputs>(new Foo {}, "outputs")
 ///
 /// // Dot access; gives a `Reference<Foo, String>`
 /// myFile = outputs.file
@@ -184,9 +175,9 @@ external const function Reference<D, T>(
 /// myFile = "{{ outputs/file }}"
 /// myProperty = "{{ outputs/properties[myProperty] }}"
 /// ```
-external class Reference<out D, out T> {
+external class Reference<out Domain, out Type> {
   /// Returns the domain this reference belongs to.
-  external function getDomain(): D
+  external function getDomain(): Domain
 
   /// Returns arbitrary data attached to the reference during creation.
   ///
@@ -197,17 +188,17 @@ external class Reference<out D, out T> {
   external function getPath(): List<Access>
 
   /// Returns a string representation of this reference using its domain's
-  /// [Domain.renderReference()] method.
+  /// [AbstractDomain.renderReference()] method.
   function toString(): String = getDomain().renderReference(this)
 }
 
 /// A configuration domain that a [Reference] may exist within.
 ///
-/// Only references with the same [Domain] are compatible with each other.
+/// Only references with the same [AbstractDomain] are compatible with each other.
 ///
 /// A domain also determines how [Reference] values are transformed into strings; see
 /// [renderReference()].
-abstract class Domain {
+abstract class AbstractDomain {
   /// Determines how [Reference] instances are transformed to strings by [Reference.toString()] and
   /// string interpolation.
   abstract function renderReference(reference: Reference<this, Any>): String

stdlib/syntax.pkl

@@ -305,6 +305,7 @@ typealias TerminalNodeType =
     | "assign"
     | "at"
     | "colon"
+    | "dcolon"
     | "comma"
     | "dot"
     | "gt"