PKL Config Scala

[andyglow]

Purpose

Adds pkl-config-scala — the binding/runtime layer that lets hand-authored Scala case classes consume Pkl configs. Mirrors pkl-config-kotlin. A follow-up will add pkl-codegen-scala so users can either hand-write or generate their Scala types.

import org.pkl.config.java.ConfigEvaluator
import org.pkl.config.scala.syntax._

case class AppConfig(name: String, port: Int, tags: Seq[String])

val config: AppConfig = ConfigEvaluator
  .preconfigured()
  .forScala()
  .evaluate(ModuleSource.text("""
    |name = "orders"
    |port = 8080
    |tags = List("beta", "team-a")
    |""".stripMargin))
  .to[AppConfig]

Built on Scala 3.3.7 (LTS). Consumable from Scala 2.13 callers via -Ytasty-reader — see Scala 2.13 cross-support below.

What's covered

Scala-specific mappings added by this module:

Pkl type	Scala target
class Foo { x: Int }	case class Foo(x: Int)
Duration	scala.concurrent.duration.Duration, FiniteDuration
Int (epoch) / String (ISO-8601)	java.time.Instant
String / Regex	scala.util.matching.Regex
Pair<A, B>	(A, B) / Tuple2[A, B]
List<T>, Set<T>, Listing<T>, Collection<T>	Seq[T]
Map<K, V>, Mapping<K, V>	immutable.Map[K, V]
Nullable T?	Option[T]
String-literal union (Pkl codegen's enum form)	Scala 3 enum Foo { case A, B } — both plain and Java-compat enum Foo extends java.lang.Enum[Foo] forms

Inherited transparently from pkl-config-java (regression-pinned in ScalaObjectMapperSpec):

• Int → java.math.BigInteger, java.math.BigDecimal, Byte, Short, Int, Float, Double
• Float → Float, BigDecimal
• String → java.lang.Character, java.net.URI, java.net.URL, java.nio.file.Path, java.io.File, Pattern
• Bytes → Array[Byte]
• DataSize, Duration, Regex identity passthroughs
• Java enum via pStringToEnum

Intentionally not covered

Users with hand-authored types register their own converter factories:

• Scala 2 scala.Enumeration — out of scope. The Scala 2.13 reflection plumbing it required is what motivated removing the earlier enum path; with Scala 3 enums supported natively, the Scala 2 form is dead weight.
• Scala Set[T], Vector[T], mutable collections — matches the minimal default set in pkl-config-java / pkl-config-kotlin.
• Scala primitive Char — Java's pStringToCharacter registers for java.lang.Character only; case classes with a Char field need to use java.lang.Character instead, or register a (String, char.class) conversion.

Module shape

Mirrors pkl-config-kotlin:

• ScalaConverterFactories.pObjectToCaseClass is new PObjectToDataObject { override selectConstructor } — same anonymous-subclass pattern as KotlinConverterFactories.pObjectToDataObject.
• ScalaConversions carries scalar conversions (Instant / Duration / Regex), analogous to KotlinConversions.
• forScala() extensions on ValueMapperBuilder / ConfigEvaluatorBuilder / ConfigEvaluator / ConfigDecoderBuilder / ConfigDecoder, plus Config.to[T]. Matches the five-receiver surface of forKotlin() in ConfigExtensions.kt.
• Parametric collection converters (Option, Pair, Map, Seq) go through a small CachedConverterFactories helper for per-type-arg caching. Same idea as Kotlin's PPairToKotlinPair, factored to keep the four factories declarative.
• PStringToScalaEnum handles idiomatic enum Foo { case A, B } by reading the companion module's synthetic values() method into an order-preserving VectorMap. For the opt-in enum Foo extends java.lang.Enum[Foo] form, Class.isEnum returns true and pkl-config-java's stock PStringToEnum handles it; our factory defers in that case to avoid double-handling.

No scala-reflect dependency.

Scala 2.13 cross-support

Built for Scala 3.3.7. Consumable from Scala 2.13 callers via the TASTy reader:

scalacOptions += "-Ytasty-reader"
libraryDependencies += "org.pkl-lang" %% "pkl-config-scala" % "X.Y.Z"

Works for the 2.13 consumer:

• forScala() builder extensions and Config.to[T] — kept as implicit class (pre-Scala 3 form), TASTy-readable.
• 2.13 case classes — implement scala.Product, which is what pObjectToCaseClass checks for.
• All collection / Option / Pair / regex / duration converters — use scala.collection.immutable.*, common to both Scala versions.

Does not work:

• Scala 2 Enumeration — never supported by this module.
• Scala 3 enum — 2.13 has no enum keyword; PStringToScalaEnum is dead-but-harmless code on the consumer side.

A follow-up could wire a smoke-test module that compiles against Scala 2.13 with -Ytasty-reader and consumes pkl-config-scala_3, to catch TASTy-reader regressions automatically.

Notes

• Default converter set trimmed to match pkl-config-java / pkl-config-kotlin. Users register their own for Set / Vector / mutable collections.
• Scala-native types preferred internally (TrieMap, Scala Option + .toJava at Java boundaries). Java types kept only where the API demands them (java.lang.reflect.*, MethodHandle, Optional return).
• POM publishing wiring (the library vs fatJar ambiguity that pkl-config-kotlin.gradle.kts works around with manual XML injection) will be addressed in a follow-up; not required for this PR's scope.

[bioball]

Made a first pass. Thanks for the contribution, this looks like a great start!

[bioball]

Move this to pklScalaLibrary.gradle.kts

[andyglow]

Done

[bioball]

Remove (this is redundant when setting scala.scalaVersion)

Suggested change

api(libs.scalaLibrary)

[andyglow]

Removed api(libs.scalaLibrary) — redundant now that the plugin wires it in.

[bioball]

These should be thread-safe, because ValueMappers can possibly be shared across threads.

Maybe put inside AtomicReference?

[andyglow]

Done. Merged the two vars into a single AtomicReference[Entry(classInfo, converter)] so the paired state updates coherently — no risk of a reader seeing a new classInfo with a stale converter. Under contention, threads may each compute a fresh converter (wasted getConverter lookup), but never see a torn state.

[bioball]

Two comments:

1. This should return Optional.empty if sourceType is not PClassInfo.String
2. The return type should be Optional[Converter[String, Enumeration]] right? Is there any case where the mapped value wouldn't be an Enumeration?

[andyglow]

Both points addressed, but the final shape diverged from the initial refactor. Enum params no longer go through the generic ConverterFactory.create path at all — they're dispatched directly via pattern match on Param.Type.ScalaEnum inside ScalaPObjectToCaseClass (see #12). So the question of whether to tighten the Optional[Converter[_, _]] signature is moot: the wildcard never participates in enum resolution anymore. The inner lookup is strongly typed: String => Enumeration#Value.

[bioball]

Remove unused code

[andyglow]

Removed — both the commented-out block and its entry in all.

[bioball]

I'm not totally following the code here.

Why do we need to care about case classes here? Can we expect enums to simply look like this instead?

object SimpleEnum extends Enumeration {
  val Aaa, Bbb, Ccc = Value
}

And we can just use .values to access enum members during conversion.

Pkl only turns string literal unions into enums in every other language; this means that we don't need our enum values to be parameterized.

[andyglow]

Done — and the annotation is deleted, not just optional. Both forms work now:

// plain — previously unsupported
object Color extends Enumeration { val Red, Green, Blue = Value }
case class Palette(primary: Color.Value)

// nested-Val form, still supported, no annotation needed
object Shape extends Enumeration {
  case class V() extends Val(nextId)
  val Circle, Square = V()
}
case class Drawing(shape: Shape.V)

Getting there required more than .getDeclaringClass. For the plain form the runtime class is scala.Enumeration$Value, shared across every Enumeration in the JVM — Java reflection can't distinguish owners. I explored three workarounds before settling on the current approach:

1. Pre-substitute resolved Value instances into the PObject's property map and delegate. Dead — PClassInfo.forValue throws on non-Pkl values.
2. Swap enum-param Types for a sentinel ParameterizedType carrying the Enumeration reference. Dead — ValueMapperImpl.getConverter calls Reflection.getExactSubtype(...) before factory dispatch, which normalises custom Types back to their raw class.
3. Upstream patch (make create non-final / add a per-param hook). Out of scope for this PR.

What we landed on:

• ConstructorParamResolver uses scala.reflect.runtime.universe only to walk ctor params and recover the path-dependent Enumeration#Value prefix. It emits pure-data Params with a sealed Param.Type { Jvm | ScalaEnum }.
• ScalaPObjectToCaseClass forks PObjectToDataObject.ConverterImpl and dispatches on Param.Type directly. For ScalaEnum it bypasses ValueMapper.getConverter (which can't see past the erasure) and does a direct member lookup.

The fork is the main cost — roughly 150 lines duplicated from PObjectToDataObject.ConverterImpl.convert. Happy to collapse it if you'd accept an upstream patch exposing a per-param hook; that would reduce this module to a slim subclass. Architectural details are in the updated PR description.

[ktham]

Really excited to see some momentum on Scala support for pkl! I think it could be a good alternative to lightbend/config and pureconfig if there were first-class Scala support.

I see this PR specifically targets Scala 2.13. One thing that stands out to me is that it isn't clear what would happen to code that won't compile under Scala 3, e.g. scala.reflect.runtime.universe. Would we have separate directories for Scala 2-specific code? And what would the Gradle build look like?

Given that Scala 3 was released ~5 years ago and most actively maintained Scala projects now cross-compile, it might be worth attempting a Scala 3 cross-build before merging the initial Scala 2 support to surface any surprises early and to have clarity on whether there are any known blockers.

Either way, if Scala support is being prioritized for an upcoming pkl release, I'd love to see a Scala 3 variant simultaneously land as part of that same release 🙂 (I'd be happy to take a look and help with that!)

[andyglow]

Hello @ktham.
The plans are wide. We will start from a reflection based (to mimic approaches taken for java and kotlin) minimal implementation for 2.13 (+ scala 3 cross-compilation).

The plan is though to than gradually drift to macro based solution. @bioball correct me if i'm wrong.
I also have a pureconfig-pkl prototype that we potentially can add later on. And maybe for Ciris.
As well as there is a plan for adding scalameta based codegen.

[bioball]

On scala.reflect.runtime.universe: the reason this is used is to support decoding Enumeration objects. However, we've been chatting about how to best support enums in Scala, and I'm kind of bearish on supporting Enumeration; our object mapper currently relies on Java reflection, and Scala's Enumeration values are erased into just scala.Enumeration$Value.

And yeah; I think we do want to move towards generated deserializers for JVM languages. I think this would be implemented as annotation processors on the Java/Kotlin side. Maybe macros for Scala, although I think that might also be challenging if we want to support both Scala 2 and 3.

[odenix]

For a library first released in 2026, I’d focus on Scala 3 and wouldn’t support Scala 2 anymore. I’m also worried that adding pkl-scala to this repo could make the Gradle build much heavier, like the internal IntelliJ plugin did before being moved out. (I’d also love to see pkl-gradle moved out, which currently dominates build time.)

[andyglow]

hi folks. thanks for the feedbacks. appreciate it

following your recommendations i have rewritten it to scala 3
so scala 3 is a first class citizen. scala 3 enums got supported too.

with -Ytasty-reader its enabling scala 2.13 projects too (no enum support for scala 2 though)

[bioball]

Did another pass! This is looking great! I think the biggest problem here is that ClassTag doesn't give us type arguments of generic types.

[bioball]

This will lose any type arguments to T; e.g. to[Seq[Int]].

I think there's a couple ways around this:

1. We copy what we do in Java (see org.pkl.config.java.JavaType), and offer a ScalaType API
2. We implement this as a macro (for both scala 2 and 3 if we want to ensure continued 2.13 support)
3. We use izumi-reflect's Tag

[bioball]

Ah, this also doesn't handle union types, or string literal types, e.g.

config.to["hello"] // downgrades to `to[String]`
config.to[Int | Boolean] // downgrades to `to[Object]`

[andyglow]

yes.. definitely. i missed that as we don't have cases for it. but it is definitely a gap
the easiest fix would be to incorporate izumi. but.. are we ok for external dependency?
we definitely can solve on our own. it will require some boilerplate though if we want to support 2.13 as the fix that will work for scala 3 will not be accepted by 2.13 even if it's a 3.7 sadly. so we will need cross-version compilation with all the corresponding "benefits"

let me create tests and solve it for just 3 at this point and we will see what to do next

[bioball]

Suggested change

	*/
	*/
	//noinspection ScalaWeakerAccess

[bioball]

Suggested change

	(v: PDuration, _) => Duration.fromNanos(v.inNanos()).toCoarsest
	(v: PDuration, _) => {
	val unit = v.getUnit match {
	case DurationUnit.NANOS => TimeUnit.NANOSECONDS
	case DurationUnit.MICROS => TimeUnit.MICROSECONDS
	case DurationUnit.MILLIS => TimeUnit.MILLISECONDS
	case DurationUnit.SECONDS => TimeUnit.SECONDS
	case DurationUnit.MINUTES => TimeUnit.MINUTES
	case DurationUnit.HOURS => TimeUnit.HOURS
	case DurationUnit.DAYS => TimeUnit.DAYS
	}
	Duration(v.getValue, unit)
	}

[andyglow]

mmm. ok. explicit it is

[bioball]

You won't get either Option or Optional from Pkl.

Also: Some constructor feels more idiomatic

Suggested change

	case v: Option[_] => v.map(s1.updateAndGet(_, t1, vm))
	case v: Optional[_] => v.toScala.map(s1.updateAndGet(_, t1, vm))
	case v => Option(s1.updateAndGet(v, t1, vm))
	case v => Some(s1.updateAndGet(v, t1, vm))

[bioball]

Better to delegate to Java implementation (find constructor whose argument count matches field count) in case Scala synthesizes multiple constructors per case class.

Suggested change

	clazz.getDeclaredConstructors.headOption
	.filter(_ => {
	// case classes all implement Product
	clazz.getInterfaces
	.exists(i => classOf[scala.Product].isAssignableFrom(i))
	})
	.toJava
	// case classes all implement Product
	if (!clazz.getInterfaces.exists(i => classOf[scala.Product].isAssignableFrom(i))) {
	return Optional.empty()
	}
	super.selectConstructor(clazz)

[bioball]

I don't see any code here that defers?

[bioball]

Suggested change

	object ScalaConverterFactories {
	//noinspection ScalaWeakerAccess
	object ScalaConverterFactories {

[bioball]

[nit] share the same evaluator across all tests

If we can't, then do Using(ConfigEvaluatorBuilder.preconfigured().forScala().build()) { evaluator =>

[bioball]

Suggested change

	description.set("Scala config library based on the Pkl config language.")
	description.set("Scala extensions for pkl-config-java, a Java config library based on the Pkl config language.")

[andyglow]

this is a nice point to discuss
if you remember well my very first version of this lib was built using scala macros (2.13 though)
it didn't require pkl-config-java. than there was ask to unify and now we're closing the loop. which is fine, but i want to emphasize that bringing two toolsets for solving one problem is even more confusing.
per my understanding it's either

• pkl-config-java extension and then it uses Conversions/ConversionFactories and the stuff all over the stack
• or it's pure scala with no reflection at all - macro/shapeless/magnolia/izumi - this kind of stack, no java reflection no dependency on pkl-config-java

what do you think?

[bioball]

Not necessarily blocking this PR: if our goal is to support both Scala 2.13 and Scala 3, we should be testing the library from both targets.

[andyglow]

i think we should produce scala 3..
scala 2.13 consumers can pull scala 3 library
https://www.scala-lang.org/blog/state-of-tasty-reader.html

so at this point we can lock at 3.7 and scale ro 2.13 and 3.8 later

[bioball]

Suggested change

@file:Suppress("HttpUrlsUsage", "unused")