docs: Add documentation for uPickle module

Iltotore · Dec 30, 2023 · 5825bbc · 5825bbc
1 parent fc18ee2
commit 5825bbc
Show file tree

Hide file tree

Showing 5 changed files with 68 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -101,6 +101,7 @@ ivy"io.github.iltotore::iron:version"
 | iron-jsoniter   | ✔️  | ✔️ | ✔️     |
 | iron-scalacheck | ✔️  | ✔️ | ❌     |
 | iron-skunk      | ✔️  | ✔️ | ✔️     |
+| iron-upickle    | ✔️  | ✔️ | ✔️     |
 | iron-zio        | ✔️  | ✔️ | ❌     |
 | iron-zio-json   | ✔️  | ✔️ | ❌     |
 

diff --git a/build.sc b/build.sc
@@ -77,7 +77,8 @@ object docs extends BaseModule {
 
   def artifactName = "iron-docs"
 
-  val modules: Seq[ScalaModule] = Seq(main, cats, circe, decline, doobie, upickle, ciris, jsoniter, scalacheck, skunk, zio, zioJson)
+  val modules: Seq[ScalaModule] =
+    Seq(main, cats, circe, decline, doobie, upickle, ciris, jsoniter, scalacheck, skunk, upickle, zio, zioJson)
 
   def docSources = T.sources {
     T.traverse(modules)(_.docSources)().flatten
@@ -130,16 +131,17 @@ object docs extends BaseModule {
     else "main"
   }
 
-  def externalMappings = Map(
+  def externalMappings = Seq(
     ".*cats.*" -> ("scaladoc3", "https://javadoc.io/doc/org.typelevel/cats-docs_3/latest/"),
     ".*io.circe.*" -> ("scaladoc2", "https://circe.github.io/circe/api/"),
     ".*ciris.*" -> ("scaladoc2", "https://cir.is/api/"),
     ".*com.monovore.decline.*" -> ("scaladoc3", "https://javadoc.io/doc/com.monovore/decline_3/latest/"),
     ".*doobie.*" -> ("scaladoc3", "https://www.javadoc.io/doc/org.tpolecat/doobie-core_3/latest/"),
     ".*com.github.plokhotnyuk.jsoniter_scala.core.*" -> ("scaladoc3", "https://www.javadoc.io/doc/com.github.plokhotnyuk.jsoniter-scala/jsoniter-scala-core_3/latest/"),
     ".*org.scalacheck.*" -> ("scaladoc3", "https://javadoc.io/doc/org.scalacheck/scalacheck_3/latest/"),
-    ".*org.scalacheck.*" -> ("scaladoc3", "https://javadoc.io/doc/org.scalacheck/scalacheck_3/latest/"),
     ".*skunk.*" -> ("scaladoc3", "https://javadoc.io/doc/org.tpolecat/skunk-docs_3/latest/"),
+    ".*upickle.core.*" -> ("scaladoc3", "https://javadoc.io/doc/com.lihaoyi/upickle-core_3/latest/"),
+    ".*upickle[^\\.core].*" -> ("scaladoc3", "https://javadoc.io/doc/com.lihaoyi/upickle_3/latest/"),
     ".*zio.json.*" -> ("scaladoc3", "https://javadoc.io/doc/dev.zio/zio-json_3/latest/"),
     ".*zio.prelude.*" -> ("scaladoc3", "https://javadoc.io/doc/dev.zio/zio-prelude-docs_3/latest/"),
     ".*zio[^\\.json].*" -> ("scaladoc3", "https://javadoc.io/doc/dev.zio/zio_3/latest/")

diff --git a/docs/_docs/modules/index.md b/docs/_docs/modules/index.md
@@ -16,6 +16,7 @@ These modules are mostly "support"/"interoperability" modules to provide out of
 - [Doobie](doobie.md): Typeclass instances for refinement types.
 - [Jsoniter](jsoniter.md): Typeclass instances for refinement types.
 - [ScalaCheck](scalacheck.md): Typeclass instances for refinement types.
+- [uPickle](upickle.md): Typeclass instances for refinement types.
 - [ZIO](zio.md): Accumulative refinement method.
 - [ZIO-Json](zio-json.md): Typeclass instances for refinement types.
 

diff --git a/docs/_docs/modules/upickle.md b/docs/_docs/modules/upickle.md
@@ -0,0 +1,60 @@
+---
+title: "uPickle Support"
+---
+
+# uPickle Support
+
+This module provides refined types Writer/Reader instances for [uPickle](https://com-lihaoyi.github.io/upickle/).
+
+## Dependency
+
+SBT:
+
+```scala 
+libraryDependencies += "io.github.iltotore" %% "iron-upickle" % "version"
+```
+
+Mill:
+
+```scala 
+ivy"io.github.iltotore::iron-upickle:version"
+```
+
+### Following examples' dependencies
+
+SBT:
+
+```scala 
+libraryDependencies += "com.lihaoyi" %% "upickle" % "3.1.3"
+```
+
+Mill:
+
+```scala 
+ivy"com.lihaoyi::upickle:3.1.3"
+```
+
+## Writer/Reader instances
+
+You can serialize and deserialize refined values using Iron's Writer/Reader instances for refined types.
+
+```scala 
+import upickle.default._
+import io.github.iltotore.iron.*
+import io.github.iltotore.iron.constraint.all.*
+import io.github.iltotore.iron.upickle.given
+
+opaque type Username = String :| Alphanumeric
+object Username extends RefinedTypeOps[String, Alphanumeric, Username]
+
+opaque type Age = Int :| Positive
+object Age extends RefinedTypeOps[Int, Positive, Age]
+
+case class User(name: Username, age: Age) derives ReadWriter
+
+write(User("Iltotore", 19)) //{"name":"Iltotore","age":19}
+
+read[User]("""{"name":"Iltotore","age":19}""") //User("Iltotore", 19)
+read[User]("""{"name":"Iltotore","age":-19}""") //AbortException: Should be strictly positive
+read[User]("""{"name":"Il_totore","age":19}""") //AbortException: Should be alphanumeric
+```
diff --git a/docs/sidebar.yml b/docs/sidebar.yml
@@ -26,5 +26,6 @@ subsection:
       - page: modules/jsoniter.md
       - page: modules/skunk.md
       - page: modules/scalacheck.md
+      - page: modules/upickle.md
       - page: modules/zio.md
       - page: modules/zio-json.md