diff --git a/.gitignore b/.gitignore index 1a36958243..dc35ce5458 100644 --- a/.gitignore +++ b/.gitignore @@ -19,4 +19,5 @@ TAGS *.sublime-workspace tests.iml # Auto-copied by sbt-microsites -docs/src/main/tut/contributing.md \ No newline at end of file +docs/src/main/tut/contributing.md +docs/src/main/tut/index.md diff --git a/README.md b/README.md index 4e13c92953..fddb01fac0 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ ## Cats +![cats image](http://plastic-idolatry.com/erik/cats2.png) [![Build Status](https://api.travis-ci.org/typelevel/cats.svg)](https://travis-ci.org/typelevel/cats) [![Workflow](https://badge.waffle.io/typelevel/cats.svg?label=ready&title=Ready)](https://waffle.io/typelevel/cats) @@ -9,18 +10,14 @@ ### Overview -Cats is a library which provides abstractions for functional programming in Scala. - +Cats is a library which provides abstractions for functional programming in the [Scala programming language](https://scala-lang.org). The name is a playful shortening of the word *category*. -![cats image](http://plastic-idolatry.com/erik/cats2.png) +Scala supports both object-oriented and functional programming, and this is reflected in the hybrid approach of the +standard library. Cats strives to provide functional programming abstractions that are core, [binary compatible](http://typelevel.org/cats/#binary-compatibility-and-versioning), [modular](http://typelevel.org/cats/motivations#modularity), [approachable](http://typelevel.org/cats/motivations#approachability) and [efficient](http://typelevel.org//cats/motivations#efficiency). A broader goal of Cats is to provide a foundation for an [ecosystem of pure, typeful libraries](https://typelevel.org/cats/#ecosystem) to support functional programming in Scala applications. -#### Why? +For more detail about Cats' motivations, go [here](http://typelevel.org/cats/motivations). -Scala supports both object-oriented and functional programming, and this is reflected in the hybrid approach of the -standard library. Cats augments the standard library with tools that further enable functional programming such as -`Validated`, `Monad`, and `Traverse`. A broader goal of Cats is to provide a foundation for an -[ecosystem of pure, typeful libraries](https://github.com/typelevel/cats#the-cats-ecosystem). ### Getting Started @@ -51,77 +48,62 @@ functionality, you can pick-and-choose from amongst these modules * [`cats-mtl`](https://github.com/typelevel/cats-mtl): transformer typeclasses for cats' Monads, Applicatives and Functors. * [`alleycats`](https://github.com/non/alleycats): cats instances and classes which are not lawful. * [`mouse`](https://github.com/benhutchison/mouse): a small companion to cats that provides convenient syntax (aka extension methods) - - -Release notes for Cats are available in [CHANGES.md](CHANGES.md). - -*Cats is still under active development. While we don't anticipate any - major redesigns, changes that are neither source nor binary - compatible are to be expected in upcoming cats releases. We will - update the minor version of cats accordingly for such changes. Once - cats 1.0 is released (ETA: Q4 2017), there will be an increased focus - on making changes in compatible ways.* #### Enhancing type inference -To use cats you'll need sometimes support for improved type inference. To enable it for any supported Scalac version, use this [sbt plugin](https://github.com/fiadliel/sbt-partial-unification#sbt-partial-unification). - -### Documentation - -Cats information and documentation is available on the -[website](http://typelevel.org/cats). + To use cats you'll need sometimes support for improved type inference. To enable it for any supported Scalac version, use this [sbt plugin](https://github.com/fiadliel/sbt-partial-unification#sbt-partial-unification). -We also have a Scaladoc [index](http://typelevel.org/cats/api/#package). +Release notes for Cats are available in [CHANGES.md](https://github.com/typelevel/cats/blob/master/CHANGES.md). -Finally, we have a list of -[frequently-asked questions](docs/src/main/tut/faq.md). +*Cats is still under active development. While we don't anticipate any + major redesigns, changes that are neither source nor binary + compatible are to be expected in upcoming RC1 and 1.0 releases.* -Our goal is to have clear and comprehensive documentation. If you -notice problems, omissions, or errors, please -[let us know](CONTRIBUTING.md). -### The cats ecosystem +### The cats ecosystem -Many projects integrate with cats. By sharing the same set of -type classes, instances and data types, projects can speak the same "cats -language", and integrate with each other with ease. +By sharing the same set of type classes, instances and data types provided by cats, projects can speak the same "cats language", and integrate with each other with ease. #### General purpose libraries to support pure functional programming - * [Dogs](https://github.com/stew/dogs): pure functional collections and data structures. + * [Dogs](https://github.com/stew/dogs): pure functional collections and data structures + * [eff](https://github.com/atnos-org/eff): functional effects and effect handlers (alternative to monad transformers) + * [Freestyle](https://github.com/47deg/freestyle): pure functional framework for Free and Tagless Final apps & libs + * [iota](https://github.com/frees-io/iota): Fast [co]product types with a clean syntax * [Kittens](https://github.com/milessabin/kittens): automatic type class derivation for Cats and generic utility functions - * [eff](https://github.com/atnos-org/eff): functional effects and effect handlers (alternative to monad transformers). - * [Freestyle](https://github.com/47deg/freestyle): pure functional framework for Free and Tagless Final apps & libs. * [mainecoon](https://github.com/kailuowang/mainecoon): Transform and compose tagless final encoded algebras - * [iota](https://github.com/frees-io/iota): Fast [co]product types with a clean syntax + * [Monocle](https://github.com/julien-truffaut/Monocle): an optics library for Scala (and Scala.js) strongly inspired by Haskell Lens. + * [newts](https://github.com/julien-truffaut/newts): Defines newtypes compatible with cats type classes * [origami](https://github.com/atnos-org/origami): monadic folds - * [newts](https://github.com/julien-truffaut/newts): Defines newtypes compatible with cats type classes. - + * [refined](https://github.com/fthomas/refined): simple refinement types for Scala + #### Libraries with more specific uses - * [Circe](https://github.com/circe/circe): pure functional JSON library. - * [Fetch](https://github.com/47deg/fetch): efficient data access to heterogeneous data sources. - * [Frameless](https://github.com/typelevel/frameless): Expressive types for Spark. - * [FS2](https://github.com/functional-streams-for-scala): compositional, streaming I/O library - * [doobie](https://github.com/tpolecat/doobie): a pure functional JDBC layer for Scala - * [Monix](https://github.com/monix/monix): high-performance library for composing asynchronous and event-based programs. - * [http4s](https://github.com/http4s/http4s): A minimal, idiomatic Scala interface for HTTP - * [hammock](https://github.com/pepegar/hammock): Purely functional HTTP client * [atto](https://github.com/tpolecat/atto): friendly little text parsers + * [circe](https://github.com/circe/circe): pure functional JSON library * [decline](https://github.com/bkirwi/decline): A composable command-line parser - * [seals](https://github.com/durban/seals): tools for schema evolution and language-integrated schemata + * [doobie](https://github.com/tpolecat/doobie): a pure functional JDBC layer for Scala + * [Fetch](https://github.com/47deg/fetch): efficient data access to heterogeneous data sources + * [finch](https://github.com/finagle/finch): Scala combinator library for building Finagle HTTP services + * [Frameless](https://github.com/typelevel/frameless): Expressive types for Spark + * [FS2](https://github.com/functional-streams-for-scala): compositional, streaming I/O library * [grafter](https://github.com/zalando/grafter): dependency-injection library using the `Reader` pattern - * [finch](https://github.com/finagle/finch): Scala combinator library for building Finagle HTTP services + * [hammock](https://github.com/pepegar/hammock): Purely functional HTTP client + * [http4s](https://github.com/http4s/http4s): A minimal, idiomatic Scala interface for HTTP + * [monadic-html](https://github.com/OlivierBlanvillain/monadic-html): Tiny DOM binding library for Scala.js + * [Monix](https://github.com/monix/monix): high-performance library for composing asynchronous and event-based programs * [pureconfig](https://github.com/pureconfig/pureconfig): A boilerplate-free library for loading configuration files - - + * [scanamo](https://github.com/guardian/scanamo): simpler DynamoDB access for Scala + * [seals](https://github.com/durban/seals): tools for schema evolution and language-integrated schemata + *Feel free to submit a PR if you want a project you maintain to be added to this list.* +*The full-size [cats logo](https://typelevel.org/cats/img/cats-logo.png) is available for use for Cats related projects, contents, souvenirs, etc.* ### How can I contribute to Cats? We welcome contributions to Cats and would love for you to help build -Cats. See our [contributor guide](CONTRIBUTING.md) for more +Cats. See our [contributor guide](https://typelevel.org/cats/contributing.html) for more information about how you can get involved. ### Community @@ -216,4 +198,4 @@ http://opensource.org/licenses/mit-license.php and also in the [COPYING](COPYING) file. The design is informed by many other projects, in particular [Scalaz](https://github.com/scalaz/scalaz). -Copyright the maintainers, 2015-2016. +Copyright the maintainers, 2015-2017. diff --git a/build.sbt b/build.sbt index d90e7f3edc..d8db2b58c5 100644 --- a/build.sbt +++ b/build.sbt @@ -142,7 +142,12 @@ lazy val docSettings = Seq( file("CONTRIBUTING.md") -> ExtraMdFileConfig( "contributing.md", "home", - Map("title" -> "Contributing", "section" -> "contributing", "position" -> "5") + Map("title" -> "Contributing", "section" -> "contributing", "position" -> "50") + ), + file("README.md") -> ExtraMdFileConfig( + "index.md", + "home", + Map("title" -> "Home", "section" -> "home", "position" -> "0") ) ), micrositeGithubRepo := "cats", diff --git a/docs/src/main/resources/microsite/img/cats-logo.png b/docs/src/main/resources/microsite/img/cats-logo.png new file mode 100644 index 0000000000..1f3b0ea5ea Binary files /dev/null and b/docs/src/main/resources/microsite/img/cats-logo.png differ diff --git a/docs/src/main/resources/microsite/img/favicon.png b/docs/src/main/resources/microsite/img/favicon.png index b1891a4110..8c16cd9eb7 100644 Binary files a/docs/src/main/resources/microsite/img/favicon.png and b/docs/src/main/resources/microsite/img/favicon.png differ diff --git a/docs/src/main/resources/microsite/img/navbar_brand.png b/docs/src/main/resources/microsite/img/navbar_brand.png index 9570ca07ce..32dc82e202 100644 Binary files a/docs/src/main/resources/microsite/img/navbar_brand.png and b/docs/src/main/resources/microsite/img/navbar_brand.png differ diff --git a/docs/src/main/resources/microsite/img/navbar_brand2x.png b/docs/src/main/resources/microsite/img/navbar_brand2x.png index 7301a99d31..b33a891790 100644 Binary files a/docs/src/main/resources/microsite/img/navbar_brand2x.png and b/docs/src/main/resources/microsite/img/navbar_brand2x.png differ diff --git a/docs/src/main/resources/microsite/img/sidebar_brand.png b/docs/src/main/resources/microsite/img/sidebar_brand.png index 8f46827e74..6dc0cc1a82 100644 Binary files a/docs/src/main/resources/microsite/img/sidebar_brand.png and b/docs/src/main/resources/microsite/img/sidebar_brand.png differ diff --git a/docs/src/main/resources/microsite/img/sidebar_brand2x.png b/docs/src/main/resources/microsite/img/sidebar_brand2x.png index b1891a4110..8c16cd9eb7 100644 Binary files a/docs/src/main/resources/microsite/img/sidebar_brand2x.png and b/docs/src/main/resources/microsite/img/sidebar_brand2x.png differ diff --git a/docs/src/main/tut/colophon.md b/docs/src/main/tut/colophon.md index d9ecd721c1..b6f4b909ac 100644 --- a/docs/src/main/tut/colophon.md +++ b/docs/src/main/tut/colophon.md @@ -2,7 +2,7 @@ layout: page title: "Colophon" section: "colophon" -position: 6 +position: 60 --- Cats has been made a much better project, and is a much more enjoyable project to work on because of many of the other projects on which Cats diff --git a/docs/src/main/tut/datatypes.md b/docs/src/main/tut/datatypes.md index e2149881bc..0d493cea49 100644 --- a/docs/src/main/tut/datatypes.md +++ b/docs/src/main/tut/datatypes.md @@ -2,7 +2,7 @@ layout: docs title: "Data Types" section: "data" -position: 2 +position: 20 --- # Data Types diff --git a/docs/src/main/tut/faq.md b/docs/src/main/tut/faq.md index 3df454c729..0fdaf8f3ef 100644 --- a/docs/src/main/tut/faq.md +++ b/docs/src/main/tut/faq.md @@ -2,14 +2,14 @@ layout: page title: "FAQ" section: "faq" -position: 4 +position: 40 --- # Frequently Asked Questions ## Questions * [What imports do I need?](#what-imports) - * [What is the difference between cats and scalaz](#diff-scalaz) + * [What is the difference between Cats and Scalaz?](#diff-scalaz) * [Where is right-biased `Either`?](#either) * [Why is the compiler having trouble with types with more than one type parameter?](#si-2712) * [Why can't the compiler find implicit instances for Future?](#future-instances) @@ -38,10 +38,9 @@ This should be all that you need, but if you'd like to learn more about the deta ## What is the difference between Cats and Scalaz? -Cats and [Scalaz](https://github.com/scalaz/scalaz) have the same goal: facilitate pure functional programming in Scala applications; the underlying core strategy is different. Scalaz took the approach of trying to provide a single batteries-included *standard library* for FP that powers the Scala applications. Cats, on the other hand, aims to help build an [ecosystem](/cats/#ecosystem) of pure FP libraries by providing a solid and stable foundation. These libaries can have their own styles and personalities, competing with each other, while at the same time playing nice. It is through this ecosystem of FP libraries (cats included) that Scala applications can be powered with "FP awesome-ness" and beyond by picking whatever best fit their needs. +Cats and [Scalaz](https://github.com/scalaz/scalaz) have the same goal: to facilitate pure functional programming in Scala applications. However the underlying core strategy is different; Scalaz took the approach of trying to provide a single batteries-included *standard library* for FP that powers the Scala applications. Cats, on the other hand, aims to help build an [ecosystem](/cats/#ecosystem) of pure FP libraries by providing a solid and stable foundation; these libraries can have their own styles and personalities, competing with each other, while at the same time playing nice. It is through this ecosystem of FP libraries (cats included) that Scala applications can be powered with "FP awesome-ness" and beyond by picking whatever best fit their needs. -Based on this core strategy, Cats took a [modular](/cats/#modularity) approach and focuses on providing core, [binary compatible](/cats/#a-namebinary-compatibility-and-versioning), [approachable](/cats/#approachability) and [efficient](/cats/#efficiency) abstractions. It provides a welcoming and supportive environment for the [user community](https://gitter.im/typelevel/cats) governed -by the [typelevel code of conduct](https://typelevel.org/conduct). It also takes great effort in supplying a comprehensive and beginner-friendly [documentation](/cats/#documentation). +Based on this core strategy, Cats takes a [modular](/cats/motivations#modularity) approach and focuses on providing core, [binary compatible](/cats/#binary-compatibility-and-versioning), [approachable](/cats/motivations#approachability) and [efficient](/cats/motivations#efficiency) abstractions. It provides a welcoming and supportive environment for the [user community](https://gitter.im/typelevel/cats) governed by the [typelevel code of conduct](https://typelevel.org/conduct). It also takes great effort in supplying a comprehensive and beginner-friendly [documentation](/cats/#documentation). ## Where is right-biased Either? diff --git a/docs/src/main/tut/guidelines.md b/docs/src/main/tut/guidelines.md index c0bbc82b8b..8eb6acf7b9 100644 --- a/docs/src/main/tut/guidelines.md +++ b/docs/src/main/tut/guidelines.md @@ -2,7 +2,7 @@ layout: page title: "Guidelines" section: "guidelines" -position: 7 +position: 70 --- # Guidelines diff --git a/docs/src/main/tut/index.md b/docs/src/main/tut/index.md deleted file mode 100644 index 13f01e34b0..0000000000 --- a/docs/src/main/tut/index.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -layout: home -title: "Home" -section: "home" ---- -Cats is a library which provides abstractions for functional -programming in the [Scala programming language](https://scala-lang.org). -The name is a playful shortening of the word *category*. - -

Cats is a new project under active - development. Feedback and contributions are welcomed as we look - to improve it. This project is evolving quickly and we are making no - guarantees about stability until a 1.0 release is made.

- - -## Getting Started - - -Cats is currently available for Scala 2.10, 2.11, 2.12 and scala.js - -To get started with SBT, simply add the following to your build.sbt file: - -```scala -libraryDependencies += "org.typelevel" %% "cats-core" % "1.0.0-MF" -``` - -This will pull in the cats-core module. If you require some other -functionality, you can pick-and-choose from amongst these modules -(used in place of `"cats-core"`): - - * `cats-macros`: Macros used by Cats syntax (*required*). - * `cats-kernel`: Small set of basic type classes (*required*). - * `cats-core`: Most 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. - * `cats-testkit`: lib for writing tests for type class instances using laws. - - There are several other cats modules that are in separate repos so that they can - maintain independent release cycles. - - * [`cats-effect`](https://github.com/typelevel/cats-effect): standard `IO` type together with `Sync`, `Async` and `Effect` type classes - * [`cats-mtl`](https://github.com/typelevel/cats-mtl): transformer typeclasses for cats' Monads, Applicatives and Functors. - * [`alleycats`](https://github.com/non/alleycats): cats instances and classes which are not lawful. - * [`mouse`](https://github.com/benhutchison/mouse): a small companion to cats that provides convenient syntax (aka extension methods) - -Release notes for Cats are available in [CHANGES.md](https://github.com/typelevel/cats/blob/master/CHANGES.md). - - -## Motivations - - -### Approachability - -As this library evolves, we are placing a lot of emphasis on trying to -make decisions which will help keep this library approachable for -people new to the concepts in this library. We are collecting -anecdotes from successes and failures we have experienced in the past -in trying to teach others about these concepts, and trying to make -decisions which will help ease the process of getting acquainted to -the library for a newcomer. If you have any feedback for us in this -regard, we would love to hear from you. See the [Contributing -page](contributing.html) to find out ways to give us feedback. - -### Modularity - -We are trying to make the library modular. It will have a tight -core which will contain only the [type classes](typeclasses.html), -the bare minimum of data structures that are needed to support -them, and type class instances for those data structures and standard -library types. - -### Documentation - -We feel that having lots of documentation is a very important goal for -our project. It will be a big win towards our goal of -approachability. We will strive to have the code well documented, we -will strive to have lots of documentation external to the code, and we -will strive to have a large corpus of compiler verified examples of -how the software can be used. - -Writing documentation is a huge part of developing software, and one -that is often neglected. It is also a very easy way to get started -with [contributing](contributing.html) to the project - -### Efficiency - -Although unfortunately there are times when programming only with -pure functions and writing efficient code in Scala can be at odds, we -are attempting to do our best at keeping our library as efficient as -we can without making unnecessary sacrifices of purity and -usability. Where sacrifices have to be made, we will strive to make -these obvious, and will keep them well documented. - - -## The cats ecosystem - -Many projects integrate with cats. By sharing the same set of -type classes, instances and data types, projects can speak the same "cats -language", and integrate with each other with ease. - -#### General purpose libraries to support pure functional programming - - * [Dogs](https://github.com/stew/dogs): pure functional collections and data structures. - * [Kittens](https://github.com/milessabin/kittens): automatic type class derivation for Cats and generic utility functions - * [eff](https://github.com/atnos-org/eff): functional effects and effect handlers (alternative to monad transformers). - * [Freestyle](https://github.com/47deg/freestyle): pure functional framework for Free and Tagless Final apps & libs. - * [mainecoon](https://github.com/kailuowang/mainecoon): Transform and compose tagless final encoded algebras - * [iota](https://github.com/frees-io/iota): Fast [co]product types with a clean syntax - -#### Libraries with more specific uses - - * [Circe](https://github.com/circe/circe): pure functional JSON library. - * [Fetch](https://github.com/47deg/fetch): efficient data access to heterogeneous data sources. - * [Frameless](https://github.com/typelevel/frameless): Expressive types for Spark. - * [FS2](https://github.com/functional-streams-for-scala): compositional, streaming I/O library - * [doobie](https://github.com/tpolecat/doobie): a pure functional JDBC layer for Scala - * [Monix](https://github.com/monix/monix): high-performance library for composing asynchronous and event-based programs. - * [http4s](https://github.com/http4s/http4s): A minimal, idiomatic Scala interface for HTTP - * [hammock](https://github.com/pepegar/hammock): Purely functional HTTP client - * [atto](https://github.com/tpolecat/atto): friendly little text parsers - * [decline](https://github.com/bkirwi/decline): A composable command-line parser - - -## Copyright and License - - -All code is available to you under the MIT license, available at -http://opensource.org/licenses/mit-license.php and also in the -[COPYING](https://raw.githubusercontent.com/typelevel/cats/master/COPYING) file. The design is informed by many other -projects, in particular Scalaz. - -Copyright the maintainers, 2016. diff --git a/docs/src/main/tut/motivations.md b/docs/src/main/tut/motivations.md new file mode 100644 index 0000000000..3146fcc855 --- /dev/null +++ b/docs/src/main/tut/motivations.md @@ -0,0 +1,50 @@ +--- +layout: page +title: "Motivations" +section: "motivations" +position: 25 +--- + + +#### Approachability + +As this library evolves, we are placing a lot of emphasis on trying to +make decisions which will help keep this library approachable for +people new to the concepts in this library. We are collecting +anecdotes from successes and failures we have experienced in the past +in trying to teach others about these concepts, and trying to make +decisions which will help ease the process of getting acquainted to +the library for a newcomer. If you have any feedback for us in this +regard, we would love to hear from you. See the [Contributing +page](contributing.html) to find out ways to give us feedback. + +#### Modularity + +We are trying to make the library modular. It will have a tight +core which will contain only the [type classes](typeclasses.html), +the bare minimum of data structures that are needed to support +them, and type class instances for those data structures and standard +library types. + +#### Documentation + +We feel that having lots of documentation is a very important goal for +our project. It will be a big win towards our goal of +approachability. We will strive to have the code well documented, we +will strive to have lots of documentation external to the code, and we +will strive to have a large corpus of compiler verified examples of +how the software can be used. + +Writing documentation is a huge part of developing software, and one +that is often neglected. It is also a very easy way to get started +with [contributing](contributing.html) to the project. + +#### Efficiency + +Although unfortunately there are times when programming only with +pure functions and writing efficient code in Scala can be at odds, we +are attempting to do our best at keeping our library as efficient as +we can without making unnecessary sacrifices of purity and +usability. Where sacrifices have to be made, we will strive to make +these obvious, and will keep them well documented. + diff --git a/docs/src/main/tut/resources_for_learners.md b/docs/src/main/tut/resources_for_learners.md index 7c120882aa..1041040d9c 100644 --- a/docs/src/main/tut/resources_for_learners.md +++ b/docs/src/main/tut/resources_for_learners.md @@ -2,7 +2,7 @@ layout: page title: "Resources for Learners" section: "resources_for_learners" -position: 3 +position: 30 --- # Books * [Functional Programming in Scala](https://www.manning.com/books/functional-programming-in-scala) diff --git a/docs/src/main/tut/typeclasses.md b/docs/src/main/tut/typeclasses.md index b1ab831da6..8a5ab9b81e 100644 --- a/docs/src/main/tut/typeclasses.md +++ b/docs/src/main/tut/typeclasses.md @@ -2,6 +2,6 @@ layout: docs title: "Type Classes" section: "typeclasses" -position: 1 +position: 10 --- {% include_relative typeclasses/typeclasses.md %}