Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 268 lines (195 sloc) 7.755 kb
1bf9beb @mdr First commit
authored
1 Scalariform
2 ===========
3
cb9b2ad @mdr Tweaks for command line tool
authored
4 Scalariform is a code formatter for Scala 2.8. It is both a
5 stand-alone command line tool / library and an Eclipse
6 plug-in. Currently, Scalariform supports only a limited set of
7 options, although it is intended to be compatible with the
8 recommendations of the `Scala Style Guide`_ (see below). Please let me
9 know what other features people would like.
1bf9beb @mdr First commit
authored
10
11 Scalariform is licenced under `The MIT Licence`_.
12
13 .. _Scala Style Guide: http://davetron5000.github.com/scala-style/
14 .. _The MIT Licence: http://www.opensource.org/licenses/mit-license.php
15
cb9b2ad @mdr Tweaks for command line tool
authored
16 Installation in Eclipse
17 -----------------------
1bf9beb @mdr First commit
authored
18
cb9b2ad @mdr Tweaks for command line tool
authored
19 In Eclipse 3.5, install the latest nightly build of Scala IDE for
20 Eclipse using the update site mechanism:
1bf9beb @mdr First commit
authored
21
b7637b0 @mdr Update update site URL
authored
22 http://download.scala-ide.org/nightly-update-master-trunk
1bf9beb @mdr First commit
authored
23
cb9b2ad @mdr Tweaks for command line tool
authored
24 (See http://www.assembla.com/wiki/show/scala-ide/Requirements_and_Installation for more detailed instructions.)
1bf9beb @mdr First commit
authored
25
26 Then install Scalariform from this update site:
27
28 http://scalariform.googlecode.com/svn/trunk/update-site/
29
30 To format:
31
32 - Right click in the editor -> Format Scala Source Code, or
33 - Press Ctrl-Shift-D
34
35 To configure preferences, go to Window -> Preferences -> Scala -> Scala Formatter Preferences
36
cb9b2ad @mdr Tweaks for command line tool
authored
37 Command line tool
38 -----------------
39
40 Scalariform can be used as a stand-alone command line utility. Sample script::
41
42 #!/bin/bash
43 scala -cp /path/to/scalariform-X.Y.Z.jar scalariform.commandline.Main "$@"
44
45 Usage::
46
47 scalariform [options] [files...]
48
49 Options:
50 --help, -h Show help
51 --inPlace, -i Replace the input file(s) in place with a formatted version.
52 --test, -t Check the input(s) to see if they are correctly formatted, return a non-zero error code if not.
53 --verbose -v Verbose output
54
55 Preferences:
56 [+|-]alignParameters Enable/disable Align parameters on different lines in the same column
57 [+|-]compactStringConcatenation Enable/disable Omit spaces when formatting a '+' operator on String literals
58 [+|-]doubleIndentClassDeclaration Enable/disable Double indent either a class's parameters or its inheritance list
59 -indentSpaces=[1-10] Set Number of spaces to use for indentation
60 [+|-]preserveSpaceBeforeArguments Enable/disable Preserve a space before a parenthesis argument
61 [+|-]rewriteArrowSymbols Enable/disable Replace arrow tokens with unicode equivalents: => with ⇒, and <- with ←
62 [+|-]spaceBeforeColon Enable/disable Add a space before colons
63
64 Examples:
65 scalariform +spaceBeforeColon -alignParameters -indentSpaces=2 --inPlace foo.scala
66 find . -name '*.scala' | xargs scalariform +rewriteArrowSymbols --verbose --test
67 echo 'class A ( n :Int )' | scalariform
68
1bf9beb @mdr First commit
authored
69 Preferences
70 -----------
71
72 alignParameters
73 ~~~~~~~~~~~~~~~
74
75 Default: ``false``
76
77 Align class/function parameters in the same column. For example, if ``false``, then::
78
79 class Person(name: String,
80 age: Int,
81 birthdate: Date,
82 astrologicalSign: String,
83 shoeSize: Int,
84 favoriteColor: java.awt.Color)
85
86 If ``true``, then::
87
88 class Person(name: String,
89 age: Int,
90 birthdate: Date,
91 astrologicalSign: String,
92 shoeSize: Int,
93 favoriteColor: java.awt.Color)
94
95 compactStringConcatenation
96 ~~~~~~~~~~~~~~~~~~~~~~~~~~
97
98 Default: ``false``
99
100 Omit spaces when formatting a '+' operator on String literals". For example, If ``false``, then::
101
102 "Hello " + name + "!"
103
104 If ``true``, then::
105
106 "Hello "+name+"!"
107
108 The Scala Style Guide recommends_ that operators, "should `always` be
109 invoked using infix notation with spaces separated the target".
110
111 .. _recommends: http://davetron5000.github.com/scala-style/method_invocation/operators.html
112
113 doubleIndentClassDeclaration
114 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
115
116 Default: ``false``
117
118 With this set to ``true``, class (and trait / object) declarations
119 will be formatted as recommended by the `Scala Style Guide`_. That is,
120 if the declaration section spans multiple lines, it will be formatted
121 so that either the parameter section or the inheritance section is
122 doubly indented. This provides a visual distinction from the members
123 of the class. For example::
124
125 class Person(
126 name: String,
127 age: Int,
128 birthdate: Date,
129 astrologicalSign: String,
130 shoeSize: Int,
131 favoriteColor: java.awt.Color)
132 extends Entity
133 with Logging
134 with Identifiable
135 with Serializable {
136 def firstMethod = ...
137 }
138
139 Or::
140
141 class Person(
142 name: String,
143 age: Int,
144 birthdate: Date,
145 astrologicalSign: String,
146 shoeSize: Int,
147 favoriteColor: java.awt.Color) {
148 def firstMethod = ...
149 }
150
151 indentSpaces
152 ~~~~~~~~~~~~
153
154 Default: ``2``
155
156 The number of spaces to use for each level of indentation.
157
158 preserveSpaceBeforeArguments
159 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
160
161 Default: ``false``
162
163 If ``true``, the formatter will keep an existing space before a parenthesis argument. For example::
164
165 stack.pop() should equal (2)
166
167 Otherwise, if ``false``, spaces before arguments will always be removed.
168
169 rewriteArrowSymbols
170 ~~~~~~~~~~~~~~~~~~~
171
172 Default: ``false``
173
174 Replace arrow tokens with their unicode equivalents: ``=>`` with ``⇒``, and ``<-`` with ``←``. For example::
175
176 for (n <- 1 to 10) n % 2 match {
177 case 0 => println("even")
178 case 1 => println("odd")
179 }
180
181 is formatted as::
182
183 for (n ← 1 to 10) n % 2 match {
184 case 0 ⇒ println("even")
185 case 1 ⇒ println("odd")
186 }
187
188 spaceBeforeColon
189 ~~~~~~~~~~~~~~~~
190
191 Default: ``false``
192
193 Whether to ensure a space before colon. For example, If ``false``, then::
194
195 def add(a: Int, b: Int): Int = a + b
196
197 If ``true``, then::
198
199 def add(a : Int, b : Int) : Int = a + b
200
201 Scala Style Guide
202 ~~~~~~~~~~~~~~~~~
203
204 Scalariform is "compatible" with the `Scala Style Guide`_ v1.1.0 in the
205 sense that, given the right preference settings, source code that is
206 initially compiliant with the Style Guide will not become uncompliant
207 after formatting. In a number of cases, running the formatter will
208 make uncompliant source more compliant.
209
210 ============================ ========= =========
211 Preference Value Default?
212 ============================ ========= =========
213 alignParameters ``false``
214 compactStringConcatenation ``false``
215 doubleIndentClassDeclaration ``true`` No
216 indentSpaces ``2``
217 preserveSpaceBeforeArguments ``false``
218 rewriteArrowSymbols ``false``
219 spaceBeforeColon ``false``
220 ============================ ========= =========
221
222 Source directives
223 -----------------
224
225 As well as global preferences, formatting can be tweaked at the source level through comments.
226
227 format: [ON|OFF]
228 ~~~~~~~~~~~~~~~~
229
230 Disables the formatter for selective portions of a source file::
231
232 // format: OFF <-- this directive disables formatting from this point
233 class AsciiDSL {
234 n ¦- "1" -+ { n: Node =>
235 n ¦- "i"
236 n ¦- "ii"
237 n ¦- "iii"
238 n ¦- "iv"
239 n ¦- "v"
240 }
241 n ¦- "2"
242 n ¦- "3" -+ { n: Node =>
243 n ¦- "i"
244 n ¦- "ii" -+ { n: Node =>
245 n ¦- "a"
246 n ¦- "b"
247 n ¦- "c"
248 }
249 n ¦- "iii"
250 n ¦- "iv"
251 n ¦- "v"
252 }
253 // format: ON <-- formatter resumes from this point
254 ...
255 }
256 // (see: http://dev.day.com/microsling/content/blogs/main/scalajcr2.html)
257
258 format: [+|-]<preferenceName>
259 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
260
261 Sets a preference for the entire of the source file, overriding the global formatting settings::
262
263 // format: +preserveSpaceBeforeArguments
264 class StackSpec extends FlatSpec with ShouldMatchers {
265 // ...
266 stack.pop() should equal (2)
267 }
Something went wrong with that request. Please try again.