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.

Sign up for GitHub

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

Jump to bottom

Add piecemeal import guide #1756

Merged
merged 4 commits into from
Sep 12, 2017
Merged

Add piecemeal import guide #1756

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
98057a0
Add piecemeal import guide (WIP)
Jul 5, 2017
4d862c7
Fix mixup
Jul 6, 2017
723da89
Add docs for cats.data instances
Jul 7, 2017
10a5db5
Fix REPL not failing where real code would fail by removing :fail and…
Jul 12, 2017
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
27 changes: 26 additions & 1 deletion docs/src/main/tut/typeclasses/imports.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,4 +40,29 @@ val o: Option[String] = None
o.orEmpty
```

**Note**: if you import `cats.implicits._` (the preferred method), you should _not_ also use imports like `cats.syntax.option._` or `cats.instances.either._`. This can result in ambiguous implicit values that cause bewildering compile errors.
If you'd like to import à la carte, you can do so, by importing from `cats.instances` for the type class instances and `cats.syntax` for syntax enrichment.
For example, if you'd like to import the `Semigroup` instance for `String` and the corresponding syntax:
```tut:book
import cats.instances.string._
import cats.syntax.semigroup._

"Hello, " |+| "World!"
```
The first import pulls the `Semigroup` instance for String into the scope, while the second import adds the `|+|` syntax.

You can also import all syntax or all instances by importing `cats.instances.all._` or `cats.syntax.all._` respectively.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't this mixed up? I.e., it should be something like "(syntax or instances) ... (cats.syntax.all._ or cats.instances.all._) respectively". (Although english is not my first language.)


**Note**: Beware that if you import a type class instance or its syntax twice, you will receive conflicting implicits with a less than helpful error message.
This usually happens when importing different type classes in the same hierarchy or when importing syntax enrichment for all type classes using `cats.syntax.all._` or `cats.implicits._` together with a more specific import like `cats.syntax.option._` or `cats.instances.either._`.
Below is an example of this phenomenon:
```tut:fail
import cats.instances.all._
import cats.syntax.semigroup._
val x = -2 |+| 1

//now we also need access to isEmpty from Monoid
import cats.syntax.monoid._
(x |+| 1).isEmpty
```

Compilation fails on the second invocation of `|+|` because we now have conflicting implicits from `Monoid` and `Semigroup`.