From 361d4ceb3ceae8ddd461546a70af7a15491da5ad Mon Sep 17 00:00:00 2001 From: Mateusz Kubuszok Date: Wed, 25 Sep 2024 09:23:00 +0200 Subject: [PATCH] Add mention about chimney-macro-commons and chimney-engine to docs, update build.sbt for chimney-engine --- build.sbt | 27 +++++++---- .../scalaland/chimney/example/example.scala | 2 +- .../MyTypeClassDerivationPlatform.scala | 1 - .../scalaland/chimney/example/example.scala | 2 +- .../MyTypeClassDerivationPlatform.scala | 1 - docs/docs/cookbook.md | 47 +++++++++++++++++++ 6 files changed, 68 insertions(+), 12 deletions(-) diff --git a/build.sbt b/build.sbt index a56ed59b3..309b11c69 100644 --- a/build.sbt +++ b/build.sbt @@ -290,9 +290,16 @@ val ciCommand = (platform: String, scalaSuffix: String) => { def withCoverage(tasks: String*): Vector[String] = "coverage" +: tasks.toVector :+ "coverageAggregate" :+ "coverageOff" - val projects = (Vector("chimney", "chimneyCats", "chimneyProtobufs") ++ (if (isJVM) Vector("chimneyJavaCollections") - else Vector.empty)) - .map(name => s"$name${if (isJVM) "" else platform}$scalaSuffix") + val projects = for { + name <- Vector( + "chimney", + "chimneyCats", + "chimneyProtobufs", + if (isJVM) "chimneyJavaCollections" else "", + "chimneyEngine" + ) + if name.nonEmpty + } yield s"$name${if (isJVM) "" else platform}$scalaSuffix" def tasksOf(name: String): Vector[String] = projects.map(project => s"$project/$name") val tasks = if (isJVM) { @@ -325,9 +332,12 @@ lazy val root = project .settings(settings) .settings(publishSettings) .settings(noPublishSettings) - .aggregate( - (chimneyMacroCommons.projectRefs ++ chimney.projectRefs ++ chimneyCats.projectRefs ++ chimneyJavaCollections.projectRefs ++ chimneyProtobufs.projectRefs) * - ) + .aggregate(chimneyMacroCommons.projectRefs *) + .aggregate(chimney.projectRefs *) + .aggregate(chimneyCats.projectRefs *) + .aggregate(chimneyJavaCollections.projectRefs *) + .aggregate(chimneyProtobufs.projectRefs *) + .aggregate(chimneyEngine.projectRefs *) .settings( moduleName := "chimney-build", name := "chimney-build", @@ -528,10 +538,11 @@ lazy val chimneyEngine = projectMatrix description := "Chimney derivation engine exposed for reuse in other libraries" ) .settings(settings *) - .settings(versionSchemeSettings *) + .settings(versionScheme := None) // macros internal API is NOT stable yet .settings(publishSettings *) - .settings(mimaSettings *) + // .settings(mimaSettings *) // we need to get some feedback before we stabilize this .settings( + coverageExcludedPackages := "io.scalaland.chimney.internal.compiletime.*", // we're only checking if it compiles mimaFailOnNoPrevious := false // this hasn't been published yet ) .settings(dependencies *) diff --git a/chimney-engine/src/test/scala-2/io/scalaland/chimney/example/example.scala b/chimney-engine/src/test/scala-2/io/scalaland/chimney/example/example.scala index 4b8b199e6..34243c3a6 100644 --- a/chimney-engine/src/test/scala-2/io/scalaland/chimney/example/example.scala +++ b/chimney-engine/src/test/scala-2/io/scalaland/chimney/example/example.scala @@ -4,7 +4,7 @@ package object example { implicit class ConvertOps[From](private val source: From) extends AnyVal { - /** Privides the extension method on Scala 2. + /** Provides the extension method on Scala 2. * * Would allow usage of user-provided `MyTypeClass` falling back on autoderived `MyTypeClass.AutoDerived` WITHOUT * the overhead normally associated with automatic derivation. diff --git a/chimney-engine/src/test/scala-2/io/scalaland/chimney/example/macros/MyTypeClassDerivationPlatform.scala b/chimney-engine/src/test/scala-2/io/scalaland/chimney/example/macros/MyTypeClassDerivationPlatform.scala index 474db10a5..dccff020e 100644 --- a/chimney-engine/src/test/scala-2/io/scalaland/chimney/example/macros/MyTypeClassDerivationPlatform.scala +++ b/chimney-engine/src/test/scala-2/io/scalaland/chimney/example/macros/MyTypeClassDerivationPlatform.scala @@ -1,7 +1,6 @@ package io.scalaland.chimney.example.internal import io.scalaland.chimney.example.MyTypeClass -import io.scalaland.chimney.example.internal.MyTypeClassDerivation import io.scalaland.chimney.internal.compiletime.{DerivationEnginePlatform, StandardRules} /** Scala-2-specifc implementations */ diff --git a/chimney-engine/src/test/scala-3/io/scalaland/chimney/example/example.scala b/chimney-engine/src/test/scala-3/io/scalaland/chimney/example/example.scala index bdf8a6405..8830a141e 100644 --- a/chimney-engine/src/test/scala-3/io/scalaland/chimney/example/example.scala +++ b/chimney-engine/src/test/scala-3/io/scalaland/chimney/example/example.scala @@ -2,7 +2,7 @@ package io.scalaland.chimney.example extension [From](source: From) { - /** Privides the extension method on Scala 3. + /** Provides the extension method on Scala 3. * * Would allow usage of user-provided `MyTypeClass` falling back on autoderived `MyTypeClass.AutoDerived` WITHOUT the * overhead normally associated with automatic derivation. diff --git a/chimney-engine/src/test/scala-3/io/scalaland/chimney/example/internal/MyTypeClassDerivationPlatform.scala b/chimney-engine/src/test/scala-3/io/scalaland/chimney/example/internal/MyTypeClassDerivationPlatform.scala index beacafaf0..9543632c5 100644 --- a/chimney-engine/src/test/scala-3/io/scalaland/chimney/example/internal/MyTypeClassDerivationPlatform.scala +++ b/chimney-engine/src/test/scala-3/io/scalaland/chimney/example/internal/MyTypeClassDerivationPlatform.scala @@ -1,7 +1,6 @@ package io.scalaland.chimney.example.internal import io.scalaland.chimney.example.MyTypeClass -import io.scalaland.chimney.example.internal.MyTypeClassDerivation import io.scalaland.chimney.internal.compiletime.{DerivationEnginePlatform, StandardRules} /** Scala-3-specifc implementations */ diff --git a/docs/docs/cookbook.md b/docs/docs/cookbook.md index e8f24aac6..486778537 100644 --- a/docs/docs/cookbook.md +++ b/docs/docs/cookbook.md @@ -2348,3 +2348,50 @@ easier just like Neotype or other libraries described in You can find it on [GitHub](https://github.com/kevin-lee/refined4s) or [Scaladex](https://index.scala-lang.org/kevin-lee/refined4s/artifacts/refined4s-cats). + +## Reusing Chimney macros in your own macro library + +Some parts of the Chimney macros could be useful to developers of other libraries. As part of the 0.8.0 refactor, +we developed: + + - a platform-agnostic way of defining macro logic - see [Under the Hood](under-the-hood.md) for more information + - `chimney-macro-commons` - the module extracting non-Chimney-specific macro utilities: extracting fields/nullary + `def`s from classes, extracting constructors and all setters (if available), extracting enum subtypes/values, + exposing `blackbox.Context`/`Quotes` utilities in a platform-agnostic way, etc + - an automatic derivation without the standard automatic derivation overhead + - a recursive derivation engine based on the chain-of-responsibility pattern + +For now there aren't many people interested in them, so comments and Chimney-code-as-examples is the only documentation +available. + +### `chimney-macro-commons` + +This module contains no dependencies on Chimney runtime types, not Chimney-specific macro logic. It could be used to +reuse Chimney utilities for e.g.: + + - extracting `val`ues and nullary `def`s from any class + - extracting public constructors and setters + - converting between singleton `Type[A]` and `Expr[A]` + - providing a platform-agnostic utilities for some common types and expressions + +!!! note + + This module is checked by MiMa, its API should be considered stable. + +### `chimney-engine` + +This module exposes Chimney derivation engine to make it easier to use in one's own macros. It assumes that user would +implement its macro the same way as Chimney does it, and with similar assumptions +(see [Under the Hood](under-the-hood.md)). + +The only documentation is +[the example code](https://github.com/scalalandio/chimney/blob/{{ git.short_commit }}/chimney-engine/src/test/) which +illustrates how one would start developing a macro basing on Chimney engine. + +!!! warning + + This module exposes Chimney internal macros, their API can change to enable new feature development, so consider it + unstable and experimental! + + The module's version matches `chimney` version it was compiled against, but it should NOT be considered a semantic + version.