Did you ever see a Scala compiler error such as:
and had no idea what to do next? Well in this case, you need to provide an implicit instance of an ActorMaterializer
,
but the compiler isn't smart enough to be able to tell you that. Luckily, Scala Clippy is here to help!
Just add the Scala Clippy compiler plugin, and you'll see this additional helpful message, with optional additional colors:
The easiest to use Clippy is via an SBT plugin. If you'd like Clippy to be enabled for all projects, without
the need to modify each project's build, add the following to ~/.sbt/0.13/plugins/build.sbt
:
addSbtPlugin("com.softwaremill.clippy" % "plugin-sbt" % "0.6.1")
Upon first use, the plugin will download the advice dataset from https://scala-clippy.org
and store it in the
$HOME/.clippy
directory. The dataset will be updated at most once a day, in the background. You can customize the
dataset URL and local store by setting the clippyUrl
and clippyLocalStoreDir
sbt options to non-None
-values.
Note: to customize a global sbt plugin (a plugin which is added via `~/.sbt/0.13/plugins/build.sbt`) keep in mind that:
~/.sbt/0.13/build.sbt
(one directory up!). These settings will be
automatically added to all of your projects.import com.softwaremill.clippy.ClippySbtPlugin._
to access the setting names as auto-imports
don't work in the global settingsscalacOptions += "-P:clippy:colors=true"
)
From version 0.6.0 you can selectively define regexes for warnings which will be treated as fatal compilation errors. To do so with sbt,
use the clippyFatalWarnings
setting, for example:
import com.softwaremill.clippy.ClippySbtPlugin.WarningPatterns._ // ... settings( clippyFatalWarnings ++= List( NonExhaustiveMatch, ".*\\[wartremover:.*\\].*[\\s\\S]*" ) )
You can also define fatal warnings in your .clippy.json file (see further sections for examples).
Clippy can highlight:
If you'd like to enable this feature in sbt globally, add the following to `~/.sbt/0.13/build.sbt`: (see also notes above)
import com.softwaremill.clippy.ClippySbtPlugin._ // needed in global configuration only clippyColorsEnabled := true
To customize the colors, set any of `clippyColorDiff`, `clippyColorComment`, `clippyColorType`, `clippyColorLiteral`, `clippyColorKeyword` to `Some(ClippyColor.[name])`, where `[name]` can be: `Black`, `Red`, `Green`, `Yellow`, `Blue`, `Magenta`, `Cyan`, `White` or `None`.
You can of course add clippy on a per-project basis as well.
If you notice that colors don't get correctly reset, that's probably caused by problems with interpreting the standard ANSI Reset code. You can set `clippyColorReset` to a custom value like `LightGray` to solve this issue.
Help others users by submitting an advice for a compilation error that you have encountered! Just click "contribute" above and paste in your error!
Alternatively, create an issue on GitHub or chat with us on Gitter in case of any doubts.
Speaking of GitHub, you are also welcome to check out (and improve!) the plugin's & website's source code.
If you have advice that you feel is too specific to be worth sharing publicly, you can add it to your project specific advice file. First set your project root:
clippyProjectRoot := Some((baseDirectory in ThisBuild).value)Then create a file named .clippy.json in the root of your project directory and add the advice json in the format illustrated below:
{ "version": "1", "advices": [ { "error": { "type": "typeMismatch", "found": "scala\\.concurrent\\.Future\\[Int\\]", "required": "Int" }, "text": "Maybe you used map where you should have used flatMap?", "library": { "groupId": "scala.lang", "artifactId": "Future", "version": "1.0" } } ], "fatalWarnings": [ { "pattern": "match may not be exhaustive[\\s\\S]*", "text": "Additional optional text to be displayed" } ] }
You can also use Clippy directly as a compiler plugin. If you use SBT, add the following setting to your
project's .sbt
file:
addCompilerPlugin("com.softwaremill.clippy" %% "plugin" % "0.6.1" classifier "bundle")
If you are using scalac
directly, add the following option:
-Xplugin:clippy-plugin_2.11-0.6.1-bundle.jar
See clippy README for more details.