Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

WIP: added documentation for circe-derivation #1428

Closed
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion build.sbt
Original file line number Diff line number Diff line change
Expand Up @@ -182,7 +182,8 @@ lazy val docs = project
mdocIn := file("docs/src/main/tut"),
libraryDependencies ++= Seq(
"io.circe" %% "circe-generic-extras" % "0.12.2",
"io.circe" %% "circe-optics" % "0.12.0"
"io.circe" %% "circe-optics" % "0.12.0",
"io.circe" %% "circe-derivation" % "0.13.0-SNAPSHOT"
)
)
.settings(docSettings)
Expand Down
40 changes: 40 additions & 0 deletions docs/src/main/tut/codecs/semiauto-derivation.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,3 +64,43 @@ implicit val encodeUser: Encoder[User] =
```

It's not as clean or as maintainable as generic derivation, but it's less magical, it requires nothing but `circe-core`, and if you need a custom name mapping it's currently the best solution (although `0.6.0` introduces experimental configurable generic derivation in the `circe-generic-extras` module).

### circe-derivation (macro based)

Using a companion library [circe-derivation](https://github.com/circe/circe-derivation) it is easy to define semi automatic derivation with fast compile times.

```scala mdoc:silent:reset
import io.circe._, io.circe.derivation._

case class Foo(a: Int, b: String, c: Boolean)

implicit val fooDecoder: Decoder[Foo] = deriveDecoder
implicit val fooEncoder: Encoder[Foo] = deriveEncoder
```

`deriveDecoder` supports renaming, opting for using case class defaults and providing a custom discriminator, similarly `deriveEncoder` supports renaming and custom discriminator.
Thus can be used for a drop-in replacement for `io.circe.generic.semiauto`

```scala mdoc:silent:reset
import io.circe._, io.circe.derivation._

case class User(id: Long, firstName: String, lastName: String)

implicit val decodeUser: Decoder[User] = deriveDecoder(renaming.snakeCase)
implicit val encodeUser: Encoder[User] = deriveEncoder(renaming.snakeCase)
```

alternatively there is also `deriveCodec`

```scala mdoc:silent:reset
import io.circe._, io.circe.derivation._

case class User(id: Long, firstName: String, lastName: String)

val userCodec: Codec[User] = deriveCodec(renaming.snakeCase)
```

NOTE: `deriveDecoder`, `deriveEncoder` and `deriveCodec` all have default arguments. They can either be supplied no arguments, only renaming or all arguments.
The default value for `useDefaults` is `true` in case of `circe-derivation`, which is different from default behaviour of `io.circe.generic.semiauto`.

More information on `circe-derivation` is available in its [readme](https://github.com/circe/circe-derivation/blob/master/README.md)