Scala Clippy Tweet

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:

Adding the plugin

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:

• customize the plugin settings in ~/.sbt/0.13/build.sbt (one directory up!). These settings will be automatically added to all of your projects.
• you'll need to add import com.softwaremill.clippy.ClippySbtPlugin._ to access the setting names as auto-imports don't work in the global settings
• the clippy sbt settings are just a convenient syntax for adding compiler options (e.g., enabling colors is same as scalacOptions += "-P:clippy:colors=true")

(NEW!) Turning selected compilation warnings into errors

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).

Enabling syntax and type mismatch diffs highlighting

Clippy can highlight:

• in type mismatch errors, the diff between expected and actual types. This may be especially helpful for long type signatures
• syntax when displaying code fragments with errors. Example:

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.

Windows users

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.

Contributing advice

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.

Project-specific advices and fatal warnings

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"
    }
  ]
}

Library-specific advice

If you have advice that is specific to a library or library version you can also bundle the advice with your library. If your users have Scala-Clippy installed they will see your advice if your library is inclued in their project. This can be helpful in the common case where users of your library need specific imports to be able to use your functionality. To bundle clippy advice with your library just put it in a file named clippy.json in your resources directory.

Alternative ways to use Clippy

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.