Tuple docs (#184)

Author: arainko

README.md

@@ -8,10 +8,10 @@ If this project interests you, please drop a 🌟 - these things are worthless b
 
 ## Installation
 ```scala
-libraryDependencies += "io.github.arainko" %% "ducktape" % "0.2.2"
+libraryDependencies += "io.github.arainko" %% "ducktape" % "0.2.3"
 
 // or if you're using Scala.js or Scala Native
-libraryDependencies += "io.github.arainko" %%% "ducktape" % "0.2.2"
+libraryDependencies += "io.github.arainko" %%% "ducktape" % "0.2.3"
 ```
 
 NOTE: the [version scheme](https://www.scala-lang.org/blog/2021/02/16/preventing-version-conflicts-with-versionscheme.html) is set to `early-semver`

build.sbt

@@ -79,7 +79,7 @@ lazy val docs =
             ) ++ (
               // Going overboard with this since all selections are connected to each other (eg. you pick an option on of them)
               // then all of them will change, this caused screen jumps when looking at the generated code
-              (1 to 15).map(num =>
+              (1 to 25).map(num =>
                 SelectionConfig(
                   s"underlying-code-$num",
                   ChoiceConfig("visible", "User visible code"),

docs/fallible_transformations/basics.md

@@ -105,7 +105,7 @@ These will be used interchangably throughout the examples below, but if you want
 @:select(underlying-code-1)
 @:choice(visible)
 ```scala mdoc
-given Mode.Accumulating.Either[String, List] with {}
+given Mode.Accumulating.Either[String, List]()
 
 wirePerson.fallibleTo[domain.Person]
 ```
@@ -124,7 +124,7 @@ Read more about the rules under which the transformations are generated in a cha
 @:select(underlying-code-2)
 @:choice(visible)
 ```scala mdoc:nest
-given Mode.FailFast.Either[String] with {}
+given Mode.FailFast.Either[String]()
 
 wirePerson
   .into[domain.Person]
@@ -161,7 +161,7 @@ Read more in the section about [configuring fallible transformations](configurin
 @:select(underlying-code-3)
 @:choice(visible)
 ```scala mdoc:nest
-given Mode.Accumulating.Either[String, List] with {}
+given Mode.Accumulating.Either[String, List]()
 
 wirePerson.fallibleVia(domain.Person.apply)
 ```
@@ -178,7 +178,7 @@ Docs.printCode(wirePerson.fallibleVia(domain.Person.apply))
 @:select(underlying-code-4)
 @:choice(visible)
 ```scala mdoc:nest
-given Mode.FailFast.Either[String] with {}
+given Mode.FailFast.Either[String]()
 
 wirePerson
   .intoVia(domain.Person.apply)

docs/fallible_transformations/configuring_fallible_transformations.md

@@ -80,14 +80,21 @@ val good = wire.Person(name = "ValidName", age = 24, socialSecurityNo = "SOCIALN
 
 ### Product configurations
 
+|   **Name**  | **Description** |
+|:-----------------:|:-------------------:|
+|     `Field.fallibleConst`   |      a fallible variant of `Field.const` that allows for supplying values wrapped in an `F`     |
+|     `Field.fallibleComputed`   |      a fallible variant of `Field.computed` that allows for supplying functions that return values wrapped in an `F`    |
+
+---
+
 * `Field.fallibleConst` - a fallible variant of `Field.const` that allows for supplying values wrapped in an `F`
 
 @:select(underlying-code-1)
 @:choice(visible)
 ```scala mdoc:nest
 import io.github.arainko.ducktape.*
 
-given Mode.Accumulating.Either[String, List] with {}
+given Mode.Accumulating.Either[String, List]()
 
 bad
   .into[domain.Person]
@@ -119,7 +126,7 @@ Docs.printCode(
 @:select(underlying-code-2)
 @:choice(visible)
 ```scala mdoc:nest
-given Mode.Accumulating.Either[String, List] with {}
+given Mode.Accumulating.Either[String, List]()
 
 bad
   .into[domain.Person]
@@ -145,6 +152,13 @@ Docs.printCode(
 
 ### Coproduct configurations
 
+|   **Name**  | **Description** |
+|:-----------------:|:-------------------:|
+|     `Case.fallibleConst`   |      a fallible variant of `Case.const` that allows for supplying values wrapped in an `F`    |
+|     `Case.fallibleComputed`   |      a fallible variant of `Case.computed` that allows for supplying functions that return values wrapped in an `F`   |
+
+---
+
 Let's define a wire enum (pretend that it's coming from... somewhere) and a domain enum that doesn't exactly align with the wire one.
 ```scala mdoc:nest
 object wire:
@@ -161,7 +175,7 @@ object domain:
 @:select(underlying-code-3)
 @:choice(visible)
 ```scala mdoc:nest
-given Mode.FailFast.Either[String] with {}
+given Mode.FailFast.Either[String]()
 
 wire.ReleaseKind.Single
   .into[domain.ReleaseKind]
@@ -188,7 +202,7 @@ Docs.printCode(
 @:select(underlying-code-4)
 @:choice(visible)
 ```scala mdoc:nest
-given Mode.FailFast.Either[String] with {}
+given Mode.FailFast.Either[String]()
 
 // Type inference is tricky with this one. The function being passed in needs to be typed with the exact expected type.
 def handleSingle(value: wire.ReleaseKind): Either[String, domain.ReleaseKind] =
@@ -230,7 +244,7 @@ object domain:
 @:select(underlying-code-5)
 @:choice(visible)
 ```scala mdoc:nest:silent
-given Mode.Accumulating.Either[String, List] with {}
+given Mode.Accumulating.Either[String, List]()
 
 val customAccumulating =
   Transformer
@@ -258,7 +272,7 @@ And for the ones that are not keen on writing out method arguments:
 @:select(underlying-code-6)
 @:choice(visible)
 ```scala mdoc:nest:silent
-given Mode.Accumulating.Either[String, List] with {}
+given Mode.Accumulating.Either[String, List]()
 
 val customAccumulatingVia =
   Transformer

docs/fallible_transformations/definition_of_transformer_fallible_and_mode.md

@@ -11,6 +11,8 @@ So a `Fallible` transformer takes a `Source` and gives back a `Dest` wrapped in
 
 ```scala
 sealed trait Mode[F[+x]] {
+  type Self[+A] = F[A]
+
   def pure[A](value: A): F[A]
 
   def map[A, B](fa: F[A], f: A => B): F[B]
@@ -20,6 +22,14 @@ sealed trait Mode[F[+x]] {
     transformation: A => F[B]
   )(using factory: Factory[B, BColl]): F[BColl]
 }
+
+object Mode {
+  inline def current(using mode: Mode[?]): mode.type = mode
+
+  extension [F[+x], M <: Mode[F]](self: M) {
+    inline def locally[A](inline f: M ?=> A): A = f(using self)
+  }
+}
 ```
 
 Moving on to `Mode`, what exactly is it and why do we need it? So a `Mode[F]` is typeclass that gives us two bits of information:
@@ -48,3 +58,23 @@ Each one of these exposes one operation that dictates its approach to errors, `f
 For accumulating transformations `ducktape` provides instances for `Either` with any subtype of `Iterable` on the left side, so that eg. `Mode.Accumulating[[A] =>> Either[List[String], A]]` is available out of the box (under the subclass of `Mode.Accumulating.Either[String, List]`).
 
 For fail fast transformations, instances for `Option` (`Mode.FailFast.Option`) and `Either` (`Mode.FailFast.Either`) are avaiable out of the box.
+
+As for the purpose of the `Self[+A]` type member, it's to enable use cases like these:
+
+```scala mdoc
+import io.github.arainko.ducktape.*
+
+val source =
+  (
+    Right(1),
+    Right("str"),
+    Right(List(3, 3, 3)),
+    Right(4)
+  )
+
+Mode.Accumulating.either[String, List].locally {
+  source.fallibleTo[Tuple.InverseMap[source.type, Mode.current.Self]]
+}
+```
+
+...where repeatedly referring to the `F` wrapper becomes really unwieldly - that type is known to the compiler at each call site so we make it work for us in conjunction with `Mode.current` which summons the `Mode[F]` instance in the current implicit scope.

docs/fallible_transformations/making_the_most_out_of.md

@@ -64,7 +64,7 @@ Fallible transformations wrapped in some type `F` are derived automatically for
 @:select(underlying-code-1)
 @:choice(visible)
 ```scala mdoc
-given Mode.Accumulating.Either[String, List] with {}
+given Mode.Accumulating.Either[String, List]()
 
 bad.fallibleTo[Person]
 good.fallibleTo[Person]
@@ -82,7 +82,7 @@ Same goes for instances that do fail fast transformations (you need `Mode.FailFa
 @:select(underlying-code-2)
 @:choice(visible)
 ```scala mdoc:nest
-given Mode.FailFast.Either[String] with {}
+given Mode.FailFast.Either[String]()
 
 bad.fallibleTo[Person]
 good.fallibleTo[Person]

docs/index.md

@@ -4,7 +4,7 @@
 
 *ducktape* is a library for boilerplate-less and configurable transformations between case classes and enums/sealed traits for Scala 3. Directly inspired by [chimney](https://github.com/scalalandio/chimney).
 
-If this project interests you, please drop a 🌟 - these things are worthless but give me a dopamine rush nonetheless.
+If this project interests you, please [drop a 🌟](https://github.com/arainko/ducktape) - these things are worthless but give me a dopamine rush nonetheless.
 
 ## Installation
 ```scala
@@ -231,3 +231,5 @@ Docs.printCode(
 @:@
 
 Read more in the chapter dedicated to [configuring transformations](total_transformations/configuring_transformations.md).
+
+To get an idea of what transformations are actually supported head on over to [transformation rules](transformation_rules.md).

docs/total_transformations/basics.md

@@ -145,3 +145,5 @@ Docs.printCode(
 @:@
 
 Read more in the section about [configuring transformations](configuring_transformations.md).
+
+To get an idea of what transformations are actually supported head on over to [transformation rules](../transformation_rules.md).