From c5c9c4f1432391f6af9202dd89872e5aae92ca58 Mon Sep 17 00:00:00 2001 From: Jon Pretty Date: Thu, 9 Nov 2017 09:20:20 +0000 Subject: Added Scaladocs --- build.sbt | 2 +- examples/src/main/scala/decode.scala | 11 +++++++++++ examples/src/main/scala/default.scala | 12 ++++++++++++ examples/src/main/scala/eq.scala | 25 +++++++++++++++++++++---- examples/src/main/scala/show.scala | 18 ++++++++++++++++++ 5 files changed, 63 insertions(+), 5 deletions(-) diff --git a/build.sbt b/build.sbt index 5353b03..616fc48 100644 --- a/build.sbt +++ b/build.sbt @@ -64,7 +64,7 @@ lazy val buildSettings = Seq( organization := "com.propensive", scalaVersion := "2.12.4", name := "magnolia", - version := "0.2.0", + version := "0.4.0", scalacOptions ++= Seq("-deprecation", "-feature", "-Ywarn-value-discard", "-Ywarn-dead-code", "-Ywarn-nullary-unit", "-Ywarn-numeric-widen", "-Ywarn-inaccessible", "-Ywarn-adapted-args"), crossScalaVersions := Seq("2.10.6", "2.11.11", "2.12.2"), scmInfo := Some(ScmInfo(url("https://github.com/propensive/magnolia"), diff --git a/examples/src/main/scala/decode.scala b/examples/src/main/scala/decode.scala index a5d1d67..eca56d2 100644 --- a/examples/src/main/scala/decode.scala +++ b/examples/src/main/scala/decode.scala @@ -6,16 +6,25 @@ import scala.language.higherKinds import magnolia._ import scala.language.experimental.macros +/** very basic decoder for converting strings to other types */ trait Decoder[T] { def decode(str: String): T } +/** derivation object (and companion object) for [[Derivation]] instances */ object Decoder { + /** decodes strings */ implicit val string: Decoder[String] = new Decoder[String] { def decode(str: String): String = str } + + /** decodes ints */ implicit val int: Decoder[Int] = new Decoder[Int] { def decode(str: String): Int = str.toInt } + + /** binds the Magnolia macro to this derivation object */ implicit def gen[T]: Decoder[T] = macro Magnolia.gen[T] + /** type constructor for new instances of the typeclass */ type Typeclass[T] = Decoder[T] + /** defines how new [[Decoder]]s for case classes should be constructed */ def combine[T](ctx: CaseClass[Decoder, T]): Decoder[T] = new Decoder[T] { def decode(value: String) = { val (name, values) = parse(value) @@ -23,6 +32,7 @@ object Decoder { } } + /** defines how to choose which subtype of the sealed trait to use for decoding */ def dispatch[T](ctx: SealedTrait[Decoder, T]): Decoder[T] = new Decoder[T] { def decode(param: String) = { val (name, values) = parse(param) @@ -31,6 +41,7 @@ object Decoder { } } + /** very simple extractor for grabbing an entire parameter value, assuming matching parentheses */ private def parse(value: String): (String, Map[String, String]) = { val end = value.indexOf('(') val name = value.substring(0, end) diff --git a/examples/src/main/scala/default.scala b/examples/src/main/scala/default.scala index 55b0753..ea881df 100644 --- a/examples/src/main/scala/default.scala +++ b/examples/src/main/scala/default.scala @@ -6,19 +6,31 @@ import scala.language.higherKinds import magnolia._ import scala.language.experimental.macros +/** typeclass for providing a default value for a particular type */ trait Default[T] { def default: T } +/** companion object and derivation object for [[Default]] */ object Default { + type Typeclass[T] = Default[T] + + /** constructs a default for each parameter, using the constructor default (if provided), + * otherwise using a typeclass-provided default */ def combine[T](ctx: CaseClass[Default, T]): Default[T] = new Default[T] { def default = ctx.construct { param => param.default.getOrElse(param.typeclass.default) } } + /** chooses which subtype to delegate to */ def dispatch[T](ctx: SealedTrait[Default, T])(): Default[T] = new Default[T] { def default: T = ctx.subtypes.head.typeclass.default } + /** default value for a string; the empty string */ implicit val string: Default[String] = new Default[String] { def default = "" } + + /** default value for ints; 0 */ implicit val int: Default[Int] = new Default[Int] { def default = 0 } + + /** generates default instances of [[Default]] for case classes and sealed traits */ implicit def gen[T]: Default[T] = macro Magnolia.gen[T] } diff --git a/examples/src/main/scala/eq.scala b/examples/src/main/scala/eq.scala index 408f287..cd257f6 100644 --- a/examples/src/main/scala/eq.scala +++ b/examples/src/main/scala/eq.scala @@ -5,21 +5,38 @@ import scala.language.higherKinds import magnolia._ import scala.language.experimental.macros +/** typeclass for testing the equality of two values of the same type */ trait Eq[T] { def equal(value: T, value2: T): Boolean } +/** companion object to [[Eq]] */ object Eq { + + /** type constructor for the equality typeclass */ type Typeclass[T] = Eq[T] + + /** defines equality for this case class in terms of equality for all its parameters */ def combine[T](ctx: CaseClass[Eq, T]): Eq[T] = new Eq[T] { - def equal(value1: T, value2: T) = - ctx.parameters.forall { param => param.typeclass.equal(param.dereference(value1), param.dereference(value2)) } + def equal(value1: T, value2: T) = ctx.parameters.forall { param => + param.typeclass.equal(param.dereference(value1), param.dereference(value2)) + } } + /** choose which equality subtype to defer to + * + * Note that in addition to dispatching based on the type of the first parameter to the `equal` + * method, we check that the second parameter is the same type. */ def dispatch[T](ctx: SealedTrait[Eq, T]): Eq[T] = new Eq[T] { - def equal(value1: T, value2: T): Boolean = - ctx.dispatch(value1) { case sub => sub.typeclass.equal(sub.cast(value1), sub.cast(value2)) } + def equal(value1: T, value2: T): Boolean = ctx.dispatch(value1) { case sub => + sub.cast.isDefinedAt(value2) && sub.typeclass.equal(sub.cast(value1), sub.cast(value2)) + } } + /** equality typeclass instance for strings */ implicit val string: Eq[String] = new Eq[String] { def equal(v1: String, v2: String) = v1 == v2 } + + /** equality typeclass instance for integers */ implicit val int: Eq[Int] = new Eq[Int] { def equal(v1: Int, v2: Int) = v1 == v2 } + + /** binds the Magnolia macro to the `gen` method */ implicit def gen[T]: Eq[T] = macro Magnolia.gen[T] } diff --git a/examples/src/main/scala/show.scala b/examples/src/main/scala/show.scala index 4594bff..9da507c 100644 --- a/examples/src/main/scala/show.scala +++ b/examples/src/main/scala/show.scala @@ -6,21 +6,39 @@ import scala.language.higherKinds import magnolia._ import scala.language.experimental.macros +/** shows one type as another, often as a string + * + * Note that this is a more general form of `Show` than is usual, as it permits the return type to + * be something other than [[String]]. */ trait Show[Out, T] { def show(value: T): Out } +/** companion object to [[Show]] */ object Show { + + /** the type constructor for new [[Show]] instances + * + * The first parameter is fixed as [[String]], and the second parameter varies generically. */ type Typeclass[T] = Show[String, T] + + /** creates a new [[Show]] instance by labelling and joining (with `mkString`) the result of + * showing each parameter, and prefixing it with the class name */ def combine[T](ctx: CaseClass[Typeclass, T]): Show[String, T] = new Show[String, T] { def show(value: T) = ctx.parameters.map { param => s"${param.label}=${param.typeclass.show(param.dereference(value))}" }.mkString(s"${ctx.typeName.split("\\.").last}(", ",", ")") } + /** choose which typeclass to use based on the subtype of the sealed trait */ def dispatch[T](ctx: SealedTrait[Typeclass, T]): Show[String, T] = new Show[String, T] { def show(value: T): String = ctx.dispatch(value) { sub => sub.typeclass.show(sub.cast(value)) } } + /** show typeclass for strings */ implicit val string: Show[String, String] = new Show[String, String] { def show(s: String): String = s } + + /** show typeclass for integers */ implicit val int: Show[String, Int] = new Show[String, Int] { def show(s: Int): String = s.toString } + + /** bind the Magnolia macro to this derivation object */ implicit def gen[T]: Show[String, T] = macro Magnolia.gen[T] } -- cgit v1.2.3