Scalariform

Scalariform is a code formatter for Scala. It's available as a library, a stand-alone command line tool, or via integrations with various editors and build tools (listed below).

The plan is to add preferences and features as and when people ask for them, so please do raise a Github issue if it doesn't format your code the way you'd like it, and I'll see what I can do.

Scalariform is licenced under The MIT Licence_.

.. _Scala Style Guide: http://docs.scala-lang.org/style/ .. _The MIT Licence: http://opensource.org/licenses/mit-license.php

Installing with Homebrew (for OS X users)

Mac OS X users can install the scalariform CLI tool using the Homebrew_ package manager. ::

brew install scalariform

Or, if you would like to install the latest development release: ::

brew install --HEAD scalariform

.. _Homebrew: https://github.com/Homebrew/homebrew

Packaging an executable JAR

If you would like to package scalariform for use on the command line with java -jar, clone the repo and perform the following simple steps: ::

sbt "project cli" "assembly"

sbt will build one jar with all the dependencies and put it in ::

cli/target/scala-$your_scala_version/cli-assembly-$scalariform_version.jar

You can copy this to a location in your path and execute it as follows: ::

java -jar /home/me/bin/cli-assembly-$scalariform_version.jar -f -q +compactControlReadability +alignParameters +alignSingleLineCaseStatements +doubleIndentConstructorArguments +rewriteArrowSymbols +preserveSpaceBeforeArguments --stdout ~/myproject/src/main/scala/Stuff.scala > Stuff.scala

Integration with sbt

A plugin for SBT is available at https://github.com/sbt/sbt-scalariform.

Usage within a project

Have a use for the scalariform source code directly? You can use it as a build dependency: ::

"org.scalariform" %% "scalariform" % "0.2.10"

Integration with Eclipse

Scala IDE for Eclipse uses Scalariform for code formatting:

• Right click in the editor -> Source -> Format
• Press Ctrl-Shift-F

If you select some lines, only those will be formatted.

You can also configure formatting to be run as a save action (Window -> Preferences -> Java -> Editor -> Save Actions).

To set preferences, go to either

• Window -> Preferences -> Scala -> Editor -> Formatter
• Project -> Properties -> Scala Formatter

From the formatter preference window you can import/export existing preferences. See the reference.conf_ for a listing of all available preferences and their defaults.

.. _reference.conf: https://github.com/scala-ide/scalariform/blob/master/formatterPreferences.properties

Integration with Emacs/ENSIME

"ENSIME_ uses the Scalariform library to format Scala sources. Type C-c C-v f to format the current buffer."

.. _ENSIME: https://github.com/ensime/ensime-server

Integration with jEdit

See ScalaSidekick_ by Stefan Ettrup:

.. _ScalaSidekick: https://github.com/StefanE/ScalaSidekick

Run Plugins -> scalaSidekickPlugin -> Format Scala File

Integration with Maven

There is scalariform-maven-plugin_ compatible with Scalariform 0.2.x.

.. _scalariform-maven-plugin: https://github.com/tashoyan/scalariform-maven-plugin

Integration with Gradle

There is a Gradle plugin_ to run Scalariform contributed by Jeroen van Erp.

.. _Gradle plugin: https://github.com/hierynomus/scalariform-gradle-plugin

Usage (Gradle 2.1 and above)::

plugins { id "com.github.hierynomus.scalariform" version "0.1.0" }

// optionally, configure Scalariform settings scalariform { alignParameters = true alignSingleLineCaseStatements = true }

formatAllScala

See the documentation_ for further usage examples.

.. _the documentation: https://github.com/hierynomus/scalariform-gradle-plugin/blob/master/README.adoc

Integration with TextMate

See Mads Jensen's Scala TextMate bundle:

http://github.com/mads379/scala.tmbundle

Reformat using Ctrl-Shift-H.

Use with Vim

While there is no specific Vim integration at present, you can use Scalariform as an external formatter for the gg=G command by adding the following to .vimrc ::

au BufEnter *.scala setl formatprg=java\ -jar\ /home/me/bin/scalariform.jar\ -f\ -q\ +compactControlReadability\ +alignParameters\ +alignSingleLineCaseStatements\ +doubleIndentConstructorArguments\ +rewriteArrowSymbols\ +preserveSpaceBeforeArguments\ --stdin\ --stdout au BufEnter *.scala setl equalprg=java\ -jar\ /home/me/bin/scalariform.jar\ -f\ -q\ +compactControlReadability\ +alignParameters\ +alignSingleLineCaseStatements\ +doubleIndentConstructorArguments\ +rewriteArrowSymbols\ +preserveSpaceBeforeArguments\ --stdin\ --stdout

Download scalariform.jar from the latest release_

.. _latest release: https://github.com/scala-ide/scalariform/releases/latest

Command line tool

https://github.com/scala-ide/scalariform/wiki/Command-line-tool

Library

https://github.com/scala-ide/scalariform/wiki/Library

Preferences

alignArguments

Default: ``false``

Aligns multi-line arguments

For example, if ``false``, then:

.. code:: scala

  Cake(candles = 10,
    frostingFlavor = Vanilla,
    layerFlavor = Chocolate,
    iceCream = true
  )

If ``true``, then:

.. code:: scala

  Cake(candles        = 10,
       frostingFlavor = Vanilla,
       layerFlavor    = Chocolate,
       iceCream       = true
  )

This option is disabled if ``indentWithTabs`` is ``true``.

alignParameters

Default: false

Align class/function parameters (modifiers and name, type, and defaults) in three columns.

For example, if false, then:

.. code:: scala

class Person(name: String, age: Int = 24, birthdate: Date, astrologicalSign: String = "libra", shoeSize: Int, favoriteColor: java.awt.Color )

If true, then:

.. code:: scala

class Person(name: String, age: Int = 24, birthdate: Date, astrologicalSign: String = "libra", shoeSize: Int, favoriteColor: java.awt.Color )

This will also place the "implicit" keyword in parameters on its own line, whenever the parameter being formatted contains a newline::

For example, if false, then:

.. code:: scala

def formatBirthDate( implicit birthdate: Date = Date("11/11/11"), birthtime: Time ): DateTime

If true, then:

.. code:: scala

def formatBirthDate( implicit birthdate: Date = Date("11/11/11"), birthtime: Time ): DateTime

This option is disabled if indentWithTabs is true.

alignSingleLineCaseStatements

Default: ``false``

Align the arrows of consecutive single-line case statements. For example, if ``true``, then:

.. code:: scala

  a match {
    case b => 1
    case ccc => 2
    case dd => 3
  }

Is reformatted as:

.. code:: scala

  a match {
    case b   => 1
    case ccc => 2
    case dd  => 3
  }

This option is disabled if ``indentWithTabs`` is ``true``.

alignSingleLineCaseStatements.maxArrowIndent

Default: 40

When alignSingleLineCaseStatements is true there is a limit on the number of spaces that can be inserted before an arrow to align it with other case statements. This can be used to avoid very large gaps, e.g.:

.. code:: scala

a match { case Some(wibble, wobble) if wibble + wibble > wobble * wibble => 1 case ccc => 2 }

allowParamGroupsOnNewlines

Default: ``false``

When ``allowParamGroupsOnNewlines`` is ``true`` the default behavior of collapsing
param groups into a single line is disabled. This allows for the following formatting style:

.. code:: scala

  def foo[T]
    (a: A)
    (b: B)
    (implicit t: T)

compactControlReadability
~~~~~~~~~~~~~~~~~~~~~~~~~

Default: ``false``

When ``compactControlReadability`` is ``true``, then ``if``/``else`` and
``try``/``catch``/``finally`` control structures will be formatted
using `Compact Control Readability`_ style

.. _Compact Control Readability: https://en.wikipedia.org/wiki/Indent_style#Variant:_Stroustrup

.. code:: scala

  if (x == y) {
    foo()
  }
  else if (y == z) {
    bar()
  }
  else {
    baz()
  }

  try {
    foo()
  }
  catch {
    case _ => bar()
  }
  finally {
    baz()
  }


compactStringConcatenation

Default: false

Omit spaces when formatting a '+' operator on String literals. For example, if false, then:

.. code:: scala

"Hello " + name + "!"

If true, then:

.. code:: scala

"Hello "+name+"!"

The Scala Style Guide recommends_ that operators, "should always be invoked using infix notation with spaces separated the target".

.. _recommends: http://docs.scala-lang.org/style/method-invocation.html#symbolic-methodsoperators

danglingCloseParenthesis

Default: ``Prevent``

If ``Force``, any closing parentheses will be set to dangle. For example:

.. code:: scala

   Box(
     contents: List[Thing])

becomes:

.. code:: scala

   Box(
     contents: List[Thing]
   )

If ``Prevent``, all dangling parenthesis are collapsed. For example:

.. code:: scala

   Box(
     contents: List[Thing]
   )

becomes:

.. code:: scala

   Box(
     contents: List[Thing])

If ``Preserve``, scalariform will try to match what unformatted source code is already doing per parenthesis,
either forcing or preventing.

~~doubleIndentClassDeclaration~~ (Deprecated, use `doubleIndentConstructorArguments`)

Default: false

With this set to true