Merge pull request #990 from ceedubs/a-hobbits-tale

Separate free package into its own module

README.md

@@ -32,6 +32,7 @@ functionality, you can pick-and-choose from amongst these modules
  * `cats-macros`: Macros used by Cats syntax (*required*).
  * `cats-core`: Core type classes and functionality (*required*).
  * `cats-laws`: Laws for testing type class instances.
+ * `cats-free`: Free structures such as the free monad, and supporting type classes.
 
 Release notes for Cats are available in [CHANGES.md](CHANGES.md).
 
@@ -110,6 +111,7 @@ Initially Cats will support the following modules:
  * `macros`: Macro definitions needed for `core` and other projects.
  * `core`: Definitions for widely-used type classes and data types.
  * `laws`: The encoded laws for type classes, exported to assist third-party testing.
+ * `cats-free`: Free structures such as the free monad, and supporting type classes.
  * `tests`: Verifies the laws, and runs any other tests. Not published.
 
 As the type class families grow, it's possible that additional modules

build.sbt

@@ -109,7 +109,7 @@ def noDocProjects(sv: String): Seq[ProjectReference] = CrossVersion.partialVersi
 lazy val docSettings = Seq(
   autoAPIMappings := true,
   unidocProjectFilter in (ScalaUnidoc, unidoc) :=
-    inProjects(coreJVM) -- inProjects(noDocProjects(scalaVersion.value): _*),
+    inProjects(coreJVM, freeJVM) -- inProjects(noDocProjects(scalaVersion.value): _*),
   site.addMappingsToSiteDir(mappings in (ScalaUnidoc, packageDoc), "api"),
   site.addMappingsToSiteDir(tut, "_tut"),
   ghpagesNoJekyll := false,
@@ -135,7 +135,7 @@ lazy val docs = project
   .settings(tutSettings)
   .settings(tutScalacOptions ~= (_.filterNot(Set("-Ywarn-unused-import", "-Ywarn-dead-code"))))
   .settings(commonJvmSettings)
-  .dependsOn(coreJVM)
+  .dependsOn(coreJVM, freeJVM)
 
 lazy val cats = project.in(file("."))
   .settings(moduleName := "root")
@@ -148,15 +148,15 @@ lazy val catsJVM = project.in(file(".catsJVM"))
   .settings(moduleName := "cats")
   .settings(catsSettings)
   .settings(commonJvmSettings)
-  .aggregate(macrosJVM, kernelJVM, kernelLawsJVM, coreJVM, lawsJVM, testsJVM, jvm, docs, bench)
-  .dependsOn(macrosJVM, kernelJVM, kernelLawsJVM, coreJVM, lawsJVM, testsJVM % "test-internal -> test", jvm, bench % "compile-internal;test-internal -> test")
+  .aggregate(macrosJVM, kernelJVM, kernelLawsJVM, coreJVM, lawsJVM, freeJVM, testsJVM, jvm, docs, bench)
+  .dependsOn(macrosJVM, kernelJVM, kernelLawsJVM, coreJVM, lawsJVM, freeJVM, testsJVM % "test-internal -> test", jvm, bench % "compile-internal;test-internal -> test")
 
 lazy val catsJS = project.in(file(".catsJS"))
   .settings(moduleName := "cats")
   .settings(catsSettings)
   .settings(commonJsSettings)
-  .aggregate(macrosJS, kernelJS, kernelLawsJS, coreJS, lawsJS, testsJS, js)
-  .dependsOn(macrosJS, kernelJS, kernelLawsJS, coreJS, lawsJS, testsJS % "test-internal -> test", js)
+  .aggregate(macrosJS, kernelJS, kernelLawsJS, coreJS, lawsJS, freeJS, testsJS, js)
+  .dependsOn(macrosJS, kernelJS, kernelLawsJS, coreJS, lawsJS, freeJS, testsJS % "test-internal -> test", js)
   .enablePlugins(ScalaJSPlugin)
 
 
@@ -224,6 +224,16 @@ lazy val laws = crossProject.crossType(CrossType.Pure)
 lazy val lawsJVM = laws.jvm
 lazy val lawsJS = laws.js
 
+lazy val free = crossProject.crossType(CrossType.Pure)
+  .dependsOn(macros, core, tests % "test-internal -> test")
+  .settings(moduleName := "cats-free")
+  .settings(catsSettings:_*)
+  .jsSettings(commonJsSettings:_*)
+  .jvmSettings(commonJvmSettings:_*)
+
+lazy val freeJVM = free.jvm
+lazy val freeJS = free.js
+
 lazy val tests = crossProject.crossType(CrossType.Pure)
   .dependsOn(macros, core, laws)
   .settings(moduleName := "cats-tests")
@@ -245,7 +255,7 @@ lazy val jvm = project
   .settings(commonJvmSettings:_*)
 
 // bench is currently JVM-only
-lazy val bench = project.dependsOn(macrosJVM, coreJVM, lawsJVM)
+lazy val bench = project.dependsOn(macrosJVM, coreJVM, freeJVM, lawsJVM)
   .settings(moduleName := "cats-bench")
   .settings(catsSettings)
   .settings(noPublishSettings)
@@ -328,7 +338,7 @@ lazy val publishSettings = Seq(
 ) ++ credentialSettings ++ sharedPublishSettings ++ sharedReleaseProcess
 
 // These aliases serialise the build for the benefit of Travis-CI.
-addCommandAlias("buildJVM", ";macrosJVM/compile;coreJVM/compile;coreJVM/test;lawsJVM/compile;testsJVM/test;jvm/test;bench/test")
+addCommandAlias("buildJVM", ";macrosJVM/compile;coreJVM/compile;coreJVM/test;lawsJVM/compile;freeJVM/compile;testsJVM/test;freeJVM/test;jvm/test;bench/test")
 
 addCommandAlias("validateJVM", ";scalastyle;buildJVM;makeSite")
 

docs/src/main/tut/freeapplicative.md

@@ -2,7 +2,7 @@
 layout: default
 title:  "FreeApplicatives"
 section: "data"
-source: "core/src/main/scala/cats/free/FreeApplicative.scala"
+source: "free/src/main/scala/cats/free/FreeApplicative.scala"
 scaladoc: "#cats.free.FreeApplicative"
 ---
 # Free Applicative
@@ -12,6 +12,11 @@ computations as data and are useful for building embedded DSLs (EDSLs). However,
 from `Free` in that the kinds of operations they support are limited, much like the distinction
 between `Applicative` and `Monad`.
 
+## Dependency
+
+If you'd like to use cats' free applicative, you'll need to add a library dependency
+for the `cats-free` module.
+
 ## Example
 Consider building an EDSL for validating strings - to keep things simple we'll just have
 a way to check a string is at least a certain size and to ensure the string contains numbers.

docs/src/main/tut/freemonad.md

@@ -2,7 +2,7 @@
 layout: default
 title:  "FreeMonads"
 section: "data"
-source: "core/src/main/scala/cats/free/Free.scala"
+source: "free/src/main/scala/cats/free/Free.scala"
 scaladoc: "#cats.free.Free"
 ---
 
@@ -25,6 +25,9 @@ In particular, *free monads* provide a practical way to:
 
 ## Using Free Monads
 
+If you'd like to use cats' free monad, you'll need to add a library dependency
+for the `cats-free` module.
+
 A good way to get a sense for how *free monads* work is to see them in
 action. The next section uses `Free[_]` to create an embedded DSL
 (Domain Specific Language).

docs/src/site/index.md

@@ -30,6 +30,7 @@ functionality, you can pick-and-choose from amongst these modules
  * `cats-macros`: Macros used by Cats syntax (*required*).
  * `cats-core`: Core type classes and functionality (*required*).
  * `cats-laws`: Laws for testing type class instances.
+ * `cats-free`: Free structures such as the free monad, and supporting type classes.
 
 Release notes for Cats are available in [CHANGES.md](https://github.com/typelevel/cats/blob/master/CHANGES.md).
 
@@ -86,6 +87,7 @@ In an attempt to be more modular, Cats is broken up into a number of sub-project
 * *core* - contains type class definitions (e.g. Functor, Applicative, Monad), essential datatypes, and
   type class instances for those datatypes and standard library types
 * *laws* - laws for the type classes, used to validate type class instances
+ * *cats-free* - free structures such as the free monad, and supporting type classes.
 * *tests* - tests that check type class instances with laws from *laws*
 * *docs* - The source for this website
 

tests/src/test/scala/cats/tests/CoyonedaTests.scala → free/src/test/scala/cats/free/CoyonedaTests.scala

@@ -1,8 +1,8 @@
 package cats
-package tests
+package free
 
+import cats.tests.CatsSuite
 import cats.arrow.NaturalTransformation
-import cats.free.Coyoneda
 import cats.laws.discipline.{FunctorTests, SerializableTests}
 
 import org.scalacheck.Arbitrary

tests/src/test/scala/cats/tests/FreeApplicativeTests.scala → free/src/test/scala/cats/free/FreeApplicativeTests.scala

@@ -1,8 +1,8 @@
 package cats
-package tests
+package free
 
+import cats.tests.CatsSuite
 import cats.arrow.NaturalTransformation
-import cats.free.FreeApplicative
 import cats.laws.discipline.{CartesianTests, ApplicativeTests, SerializableTests}
 import cats.data.State
 

tests/src/test/scala/cats/tests/FreeTests.scala → free/src/test/scala/cats/free/FreeTests.scala

@@ -1,8 +1,8 @@
 package cats
-package tests
+package free
 
+import cats.tests.CatsSuite
 import cats.arrow.NaturalTransformation
-import cats.free.{Free, Trampoline}
 import cats.laws.discipline.{CartesianTests, MonadTests, SerializableTests}
 import cats.laws.discipline.arbitrary.function0Arbitrary
 

tests/src/test/scala/cats/tests/InjectTests.scala → free/src/test/scala/cats/free/InjectTests.scala

@@ -1,8 +1,8 @@
 package cats
-package tests
+package free
 
+import cats.tests.CatsSuite
 import cats.data.{Xor, Coproduct}
-import cats.free.{Free, Inject,:<:}
 import org.scalacheck._
 
 class InjectTests extends CatsSuite {

tests/src/test/scala/cats/tests/YonedaTests.scala → free/src/test/scala/cats/free/YonedaTests.scala

@@ -1,7 +1,7 @@
 package cats
-package tests
+package free
 
-import cats.free.Yoneda
+import cats.tests.CatsSuite
 import cats.laws.discipline.{FunctorTests, SerializableTests}
 
 import org.scalacheck.Arbitrary