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`` and ``doubleIndentConstructorArguments`` set to ``false``,
class (and trait / object) declarations that span multiple lines will be formatted so
that the inheritance section is doubly indented. This provides a visual distinction
from the members of the class. For example:

.. code:: scala

  class Person(
    name: String,
    age: Int,
    birthdate: Date,
    astrologicalSign: String,
    shoeSize: Int,
    favoriteColor: java.awt.Color)
      extends Entity
      with Logging
      with Identifiable
      with Serializable {
    def firstMethod = ...
  }

Note: ``doubleIndentConstructorArguments`` style formatting is recommended_ by the Scala Style Guide.

doubleIndentConstructorArguments

Default: false

With this set to true, class (and trait / object) declarations will be formatted as recommended_ by the Scala Style Guide. That is, if the declaration section spans multiple lines, it will be formatted so that the parameter section is doubly indented. This provides a visual distinction between the constructor arguments & the extensions. For example:

.. code:: scala

class Person( name: String, age: Int, birthdate: Date, astrologicalSign: String, shoeSize: Int, favoriteColor: java.awt.Color) extends Entity with Logging with Identifiable with Serializable { }

Or:

.. code:: scala

class Person( name: String, age: Int, birthdate: Date, astrologicalSign: String, shoeSize: Int, favoriteColor: java.awt.Color) { def firstMethod = ... }

doubleIndentMethodDeclaration


Default: ``false``

With this set to ``true``, method declarations will have an extra indentation
added to their parameter list, if it spans multiple lines.
This provides a visual distinction from the method body. For example::

  def longMethodNameIsLong(paramOneNameIsLong: String, paramTwo: String,
      paramThreeNameIsReallyLong): Unit = {
    val startOfMethod = ...
  }

Or::

  def longMethodNameIsLong(
      paramOneNameIsLong: String,
      paramTwoNameIsLong: String,
      paramThreeNameIsLong): Unit = {
    val startOfMethod = ...
  }

firstArgumentOnNewline

Default: Force

Whether or not to place the first argument of multi-line function calls on its own line.

If Force, first arguments will be on a new line:

.. code:: scala

foo( 1, 2 )

bar( 3, 4 )

If Prevent, first arguments will be on function call line:

.. code:: scala

foo(1, 2 )

bar(3, 4 )

If Preserve, first arguments will stay where they are:

.. code:: scala

foo( 1, 2 )

bar(3, 4 )

firstParameterOnNewline


Default: ``Force``

Whether or not to place the first parameter for multi-line method or constructor definition on its own line.

If ``Force``, first parameters will be on a new line:

.. code:: scala

  abstract class Person(
    name: Int,
    age: String
  ) {
    def livesIn(
      city: String,
      state: String
    ): Boolean
  }

If ``Prevent``, first parameters will be on the definition line:

.. code:: scala

  abstract class Person(name: Int,
    age: String
  ) {
    def livesIn(city: String,
      state: String
    ): Boolean
  }

If ``Preserve``, first parameters will stay where they are:

.. code:: scala

  abstract class Person(name: Int,
    age: String
  ) {
    def livesIn(
      city: String,
      state: String
    ): Boolean
  }

formatXml

Default: true

Format embedded XML literals; if false they will be left untouched.

indentLocalDefs


Default: ``false``

If ``true``, indent local methods an extra level, with the intention of distinguishing them from other statements. For example,:

.. code:: scala

  class A {
    def find(...) = {
      val x = ...
        def find0() = {
          ...
        }
      find0(...)
    }
  }

indentPackageBlocks

Default: true

Whether to indent package blocks. For example, if true:

.. code:: scala

package foo { package bar { class Baz } }

Else if false:

.. code:: scala

package foo { package bar { class Baz } }

indentSpaces


Default: ``2``

The number of spaces to use for each level of indentation.

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

indentWithTabs

Default: false

Use a tab for each level of indentation. When set to true, this ignores any setting given for indentSpaces. In addition, for the moment, alignSingleLineCaseStatements, alignArguments, and alignParameters options are not supported when indenting with tabs, and XML indentation is handled differently.

multilineScaladocCommentsStartOnFirstLine


Default: ``false``

If ``true``, start a multi-line Scaladoc comment body on same line as the opening comment delimiter:

.. code:: scala

  /** This method applies f to each
   *  element of the given list.
   */

If ``false``, start the comment body on a separate line below the opening delimiter:

.. code:: scala

  /**
   * This method applies f to each
   * element of the given list.
   */

newlineAtEndOfFile

Default: false

If true, newlines will be added at the end of all formatted files.

placeScaladocAsterisksBeneathSecondAsterisk


Default: ``false``

If ``true``, Scaladoc asterisks will be placed beneath the second asterisk:

.. code:: scala

  /** Wibble
    * wobble
    */
  class A

Otherwise, if ``false``, beneath the first asterisk:

.. code:: scala

  /** Wibble
   *  wobble
   */
  class A

preserveSpaceBeforeArguments

Default: false

If true, the formatter will keep an existing space before a parenthesis argument. For example:

.. code:: scala

stack.pop() should equal (2)

Otherwise, if false, spaces before arguments will always be removed.

rewriteArrowSymbols


Default: ``false``

Replace arrow tokens uniformly, either as Unicode symbols or as ASCII, depending on the setting of
``useUnicodeArrows``. Starting from Scala 2.13, unicode arrows are deprecated.

For example, if ``useUnicodeArrows == true``:

.. code:: scala

  for (n <- 1 to 10) n % 2 match {
    case 0 => println("even")
    case 1 => println("odd")
  }

is formatted as:

.. code:: scala

  for (n ← 1 to 10) n % 2 match {
    case 0 ⇒ println("even")
    case 1 ⇒ println("odd")
  }

singleCasePatternOnNewline

Default: true

When singleCasePatternOnNewline is false the default behavior of forcing a single case pattern onto a newline is disabled. This allows for the following formatting style:

.. code:: scala

items.map { case (key, value) => (key, transform(value)) }

spaceBeforeColon


Default: ``false``

Whether to ensure a space before all single colons. For example, if ``false``, then:

.. code:: scala

  def add[T: Numeric](a: T, b: T): Int = implictly[Numeric[T]].plus(a, b)

If ``true``, then:

.. code:: scala

  def add[T : Numeric](a : T, b : T): Int = implictly[Numeric[T]].plus(a, b)

spaceBeforeContextColon

Default: false

Whether to ensure a space before colons in context bounds (the typeclass pattern). For example, if false, then:

.. code:: scala

def newArray[T: ClassManifest](n: Int) = new ArrayT

If true, then:

.. code:: scala

def newArray[T : ClassManifest](n: Int) = new ArrayT

spaceInsideBrackets


Default: ``false``

Whether to use a space inside type brackets. For example, if ``true``, then:

.. code:: scala

  Array[ String ]

If ``false``, then:

.. code:: scala

  Array[String]

spaceInsideParentheses

Default: false

Whether to use a space inside non-empty parentheses. For example, if true, then:

.. code:: scala

def main( args : Array[String] )

If false, then:

.. code:: scala

def main(args : Array[String])

spacesAroundMultiImports


Default: ``true``

Whether or not to add spaces around multi-imports.
For example, if ``false``, then:

.. code:: scala

  import a.{b,c,d}
  import foo.{bar => baz}

If ``true``, then:

.. code:: scala

  import a.{ b, c, d }
  import foo.{ bar => baz }

Compatibility note: Versions 0.1.6 & 0.1.7 of `Scalariform` used ``false``.

spacesWithinPatternBinders

Default: true

Whether to add a space around the @ token in pattern binders. For example, if true,:

.. code:: scala

case elem @ Multi(values @ _*) =>

If false,:

.. code:: scala

case elem@Multi(values@_*) =>

useUnicodeArrows


Default: ``true``

Controls the replacement of arrows if ``rewriteArrowSymbols == true``. To use unicode arrows in your codebase
set to `true`, otherwise, set to false. For example, if ``useUnicodeArrows == false`` (and ``rewriteArrowSymbols == true``):

.. code:: scala

  for (n ← 1 to 10) n % 2 match {
    case 0 ⇒ println("even")
    case 1 ⇒ println("odd")
  }

is formatted as:

.. code:: scala

  for (n <- 1 to 10) n % 2 match {
    case 0 => println("even")
    case 1 => println("odd")
  }

Scala Style Guide

Scalariform is compatible with the Scala Style Guide_ in the sense that, given the right preference settings, source code that is initially compliant with the Style Guide will not become uncompliant after formatting. In a number of cases, running the formatter will make uncompliant source more compliant.

=========================================== ========= ========= Preference Value Default? =========================================== ========= ========= alignParameters false compactStringConcatenation false doubleIndentConstructorArguments true No indentSpaces 2 placeScaladocAsterisksBeneathSecondAsterisk true No preserveSpaceBeforeArguments false rewriteArrowSymbols false spaceBeforeColon false spaceInsideBrackets false spaceInsideParentheses false spacesAroundMultiImports false useUnicodeArrows true =========================================== ========= =========

Source Directives

As well as global preferences, formatting can be tweaked at the source level through comments.

format: [ON|OFF]


Disables the formatter for selective portions of a source file:

.. code:: scala

  // format: OFF    <-- this directive disables formatting from this point
  class AsciiDSL {
    n ¦- "1" -+ { n: Node =>
            n ¦- "i"
            n ¦- "ii"
            n ¦- "iii"
            n ¦- "iv"
            n ¦- "v"
    }
    n ¦- "2"
    n ¦- "3" -+ { n: Node =>
            n ¦- "i"
            n ¦- "ii" -+ { n: Node =>
                     n ¦- "a"
                     n ¦- "b"
                     n ¦- "c"
            }
            n ¦- "iii"
            n ¦- "iv"
            n ¦- "v"
    }
    // format: ON   <-- formatter resumes from this point
    ...
  }
  // (see: http://dev.day.com/microsling/content/blogs/main/scalajcr2.html)

format: [+|-]<preferenceName>

Sets a preference for the entirety of the source file, overriding the global formatting settings:

.. code:: scala

// format: +preserveSpaceBeforeArguments class StackSpec extends FlatSpec with ShouldMatchers { // ... stack.pop() should equal (2) }

scala-ide / scalariform

readme

Scalariform

Installing with Homebrew (for OS X users)

Packaging an executable JAR

Integration with sbt

Usage within a project

Integration with Eclipse

Integration with Emacs/ENSIME

Integration with jEdit

Integration with Maven

Integration with Gradle

Integration with TextMate

Use with Vim

Command line tool

Library

Preferences

Source Directives