magnolia

![Magnolia](https://github.com/softwaremill/magnolia/raw/scala3/banner.jpg)

[<img alt="GitHub Workflow" src="https://img.shields.io/github/actions/workflow/status/softwaremill/magnolia/ci.yml?branch=scala3&style=for-the-badge" height="24">](https://github.com/softwaremill/magnolia/actions)
[<img src="https://img.shields.io/badge/Discourse-ask%20question-blue?style=for-the-badge" height="24">](https://softwaremill.community/c/magnolia)
[<img src="https://index.scala-lang.org/softwaremill/magnolia/magnolia/latest-by-scala-version.svg?color=2465cd&style=for-the-badge" height="24">](https://index.scala-lang.org/softwaremill/magnolia/magnolia)

# Magnolia

__Magnolia__ is a generic macro for automatic materialization of typeclasses for datatypes composed from product types (e.g. case classes) and coproduct types (e.g. enums). It supports recursively-defined datatypes out-of-the-box, and incurs no significant time-penalty during compilation.

## Features

 - derives typeclasses for case classes, case objects and sealed traits
 - offers a lightweight syntax for writing derivations without needing to understand complex parts of Scala
 - builds upon Scala 3's built-in generic derivation
 - works with recursive and mutually-recursive definitions
 - supports parameterized ADTs (GADTs), including those in recursive types
 - supports typeclasses whose generic type parameter is used in either covariant and contravariant positions

## Getting Started

Given an ADT such as,
```scala
enum Tree[+T] derives Print:
  case Branch(left: Tree[T], right: Tree[T])
  case Leaf(value: T)
```
and provided a given instance of `Print[Int]` is in scope, and a Magnolia derivation for the `Print` typeclass
has been provided, we can automatically derive given typeclass instances of `Print[Tree[Int]]` on-demand, like
so,
```scala
Tree.Branch(Tree.Branch(Tree.Leaf(1), Tree.Leaf(2)), Tree.Leaf(3)).print
```
Typeclass authors may provide Magnolia derivations in the typeclass's companion object, but it is easy to create
your own.

Creating a generic derivation with Magnolia requires implementing two methods on `magnolia1.Derivation`:

* `join()` : create typeclasses for case classes ('product types')
* `split()` : create typeclasses for sealed-traits/enums ('sum types')

### Example derivations

There are many examples in the   [`examples`](examples/src/main/scala/magnolia1/examples) sub-project.

The definition of a `Print` typeclass with generic derivation might look like this
(note we're using the [Lambda syntax for Single Abstract Method types](https://www.scala-lang.org/news/2.12.0/#lambda-syntax-for-sam-types)
to instantiate the `Print` instances in `join` & `split` - that's possible because
`Print` has only a single abstract method, `print`):
```scala
import magnolia1.*

trait Print[T] {
  extension (x: T) def print: String
}

object Print extends AutoDerivation[Print]:
  def join[T](ctx: CaseClass[Print, T]): Print[T] = value =>
    ctx.params.map { param =>
      param.typec