Skip to content
Newer
Older
100644 435 lines (312 sloc) 12 KB
1bf9beb @mdr First commit
mdr authored
1 Scalariform
2 ===========
3
5864e14 @mdr Misc README updates, add example library usage code
mdr authored
4 Scalariform is a code formatter for Scala 2.8. It is a library and a
9e0b32c @mdr Actually do the correct ScalaSidekick link
mdr authored
5 stand-alone command line tool, with integrations available for
0c60045 @mdr Add an AlignSingleLineCaseStatements.MaxArrowIndent preference to lim…
mdr authored
6 Eclipse, Emacs (via ENSIME), jEdit, Maven, sbt and
7 TextMate. Currently, Scalariform supports only a limited set of
8 options, although it is intended to be compatible with the
9 recommendations of the `Scala Style Guide`_ (see below). Please let me
10 know what other features people would like.
1bf9beb @mdr First commit
mdr authored
11
12 Scalariform is licenced under `The MIT Licence`_.
13
14 .. _Scala Style Guide: http://davetron5000.github.com/scala-style/
15 .. _The MIT Licence: http://www.opensource.org/licenses/mit-license.php
16
c19a14a @mdr Update README
mdr authored
17 Download
18 --------
19
20 Scalariform is available from Scala-tools.org:
21
a91aee0 @mdr Bump versions for 0.0.8-SNAPSHOT
mdr authored
22 http://scala-tools.org/repo-releases/org/scalariform/scalariform_2.8.0/0.0.7/
c19a14a @mdr Update README
mdr authored
23
24 If you're using sbt, you can declare a dependency as follows::
25
a91aee0 @mdr Bump versions for 0.0.8-SNAPSHOT
mdr authored
26 val scalariform = "org.scalariform" %% "scalariform" % "0.0.7"
c19a14a @mdr Update README
mdr authored
27
6c71e0b @mdr Note ENSIME integration in docs
mdr authored
28 Integration with Eclipse
29 ------------------------
1bf9beb @mdr First commit
mdr authored
30
5864e14 @mdr Misc README updates, add example library usage code
mdr authored
31 Scala IDE for Eclipse uses Scalariform for formatting:
1bf9beb @mdr First commit
mdr authored
32
56bbcfb @mdr Update README for Eclipse, TextMate integrations
mdr authored
33 http://download.scala-ide.org/
1bf9beb @mdr First commit
mdr authored
34
56bbcfb @mdr Update README for Eclipse, TextMate integrations
mdr authored
35 (See http://www.assembla.com/wiki/show/scala-ide/Requirements_and_Installation
36 for more detailed instructions.)
1bf9beb @mdr First commit
mdr authored
37
5160383 @mdr Update docs
mdr authored
38 Formatting works the same in the Scala editor; that is, either
1bf9beb @mdr First commit
mdr authored
39
5160383 @mdr Update docs
mdr authored
40 - Right click in the editor -> Source -> Format
41 - Press Ctrl-Shift-F
1bf9beb @mdr First commit
mdr authored
42
5160383 @mdr Update docs
mdr authored
43 To configure preferences, go to Window -> Preferences -> Scala -> Formatter
1bf9beb @mdr First commit
mdr authored
44
5160383 @mdr Update docs
mdr authored
45 It can also perform formatting as a save action (Window -> Preferences -> Java -> Editor -> Save Actions).
1bf9beb @mdr First commit
mdr authored
46
0c60045 @mdr Add an AlignSingleLineCaseStatements.MaxArrowIndent preference to lim…
mdr authored
47 Integration with Emacs/ENSIME
48 -----------------------------
56bbcfb @mdr Update README for Eclipse, TextMate integrations
mdr authored
49
568e60c @mdr Update docs to mention ScalaSidekick for jEdit
mdr authored
50 "`ENSIME`_ uses the Scalariform library to format Scala sources. Type C-c C-v f to format the current buffer."
56bbcfb @mdr Update README for Eclipse, TextMate integrations
mdr authored
51
6c71e0b @mdr Note ENSIME integration in docs
mdr authored
52 http://aemon.com/file_dump/ensime_manual.html#tth_sEc4.8
56bbcfb @mdr Update README for Eclipse, TextMate integrations
mdr authored
53
6c71e0b @mdr Note ENSIME integration in docs
mdr authored
54 .. _ENSIME: http://github.com/aemoncannon/ensime
56bbcfb @mdr Update README for Eclipse, TextMate integrations
mdr authored
55
568e60c @mdr Update docs to mention ScalaSidekick for jEdit
mdr authored
56 Integration with jEdit
57 ----------------------
58
9e0b32c @mdr Actually do the correct ScalaSidekick link
mdr authored
59 See `ScalaSidekick`_ by Stefan Ettrup:
568e60c @mdr Update docs to mention ScalaSidekick for jEdit
mdr authored
60
61 .. _ScalaSidekick: http://github.com/StefanE/ScalaSidekick
62
63 Run Plugins -> scalaSidekickPlugin -> Format Scala File
64
c026068 Misc tweaks to merge in Maven plugin
Matt authored
65 Integration with Maven
66 ----------------------
67
68 There is a Maven plugin to run Scalariform contributed by `Adam
69 Crain`_. It is not yet on scala-tools, but you can build it from the
70 source.
71
72 .. _Adam Crain: https://github.com/jadamcrain
73
74 Usage::
75
76 <plugin>
77 <groupId>org.scalariform</groupId>
78 <artifactId>scalariform-maven-plugin</artifactId>
79 <executions>
80 <execution>
81 <phase>process-sources</phase>
82 <goals>
83 <goal>format</goal>
84 </goals>
85 <configuration>
86 <rewriteArrowSymbols>true</rewriteArrowSymbols>
87 </configuration>
88 </execution>
89 </executions>
90 </plugin>
91
56bbcfb @mdr Update README for Eclipse, TextMate integrations
mdr authored
92 Integration with sbt
93 --------------------
94
95 `sbt-scalariform`_, written by Olivier Michallat, provides an sbt plugin contributing formatting actions.
96
97 .. _sbt-scalariform: http://github.com/olim7t/sbt-scalariform
98
6c71e0b @mdr Note ENSIME integration in docs
mdr authored
99 Integration with TextMate
100 -------------------------
101
8ba9dd0 @mdr Tweak a link in README
mdr authored
102 See Mads Jensen's Scala TextMate bundle:
6c71e0b @mdr Note ENSIME integration in docs
mdr authored
103
104 http://github.com/mads379/scala.tmbundle
105
106 Reformat using Ctrl-Shift-H.
107
cb9b2ad @mdr Tweaks for command line tool
mdr authored
108 Command line tool
109 -----------------
110
5864e14 @mdr Misc README updates, add example library usage code
mdr authored
111 Scalariform includes a stand-alone command line utility. Sample script::
cb9b2ad @mdr Tweaks for command line tool
mdr authored
112
113 #!/bin/bash
a91aee0 @mdr Bump versions for 0.0.8-SNAPSHOT
mdr authored
114 scala -cp /path/to/scalariform-0.0.7.jar scalariform.commandline.Main "$@"
cb9b2ad @mdr Tweaks for command line tool
mdr authored
115
116 Usage::
117
727622e @mdr Add --encoding= option to the command line tool
mdr authored
118 Usage: scalariform [options] [files...]
cb9b2ad @mdr Tweaks for command line tool
mdr authored
119
120 Options:
727622e @mdr Add --encoding= option to the command line tool
mdr authored
121 --encoding=<encoding> Set the encoding, e.g. UTF-8. If not set, defaults to the platform default encoding.
122 --fileList=<path>, -l=<path> Read the list of input file(s) from a text file (one per line)
436edff @olim7t New commandline option to provide a file containing the list of sourc…
olim7t authored
123 --help, -h Show help
124 --inPlace, -i Replace the input file(s) in place with a formatted version.
125 --test, -t Check the input(s) to see if they are correctly formatted, return a non-zero error code if not.
727622e @mdr Add --encoding= option to the command line tool
mdr authored
126 --verbose, -v Verbose output
c19a14a @mdr Update README
mdr authored
127 --version Show Scalariform version
727622e @mdr Add --encoding= option to the command line tool
mdr authored
128
cb9b2ad @mdr Tweaks for command line tool
mdr authored
129 Preferences:
0c60045 @mdr Add an AlignSingleLineCaseStatements.MaxArrowIndent preference to lim…
mdr authored
130 [+|-]alignParameters Enable/disable Align parameters on different lines in the same column
131 [+|-]alignSingleLineCaseStatements Enable/disable Align the arrows of consecutive single-line case statements
132 [+|-]compactStringConcatenation Enable/disable Omit spaces when formatting a '+' operator on String literals
133 [+|-]doubleIndentClassDeclaration Enable/disable Double indent either a class's parameters or its inheritance list
134 [+|-]formatXml Enable/disable Format XML literals
135 [+|-]indentPackageBlocks Enable/disable Indent package blocks
136 [+|-]preserveSpaceBeforeArguments Enable/disable Preserve a space before a parenthesis argument
137 [+|-]rewriteArrowSymbols Enable/disable Replace arrow tokens with unicode equivalents: => with ⇒, and <- with ←
138 [+|-]spaceBeforeColon Enable/disable Add a space before colons
139 -alignSingleLineCaseStatements.maxArrowIndent=[1-100] Set Maximum number of spaces inserted before an arrow to align case statements
140 -indentSpaces=[1-10] Set Number of spaces to use for indentation
cb9b2ad @mdr Tweaks for command line tool
mdr authored
141
142 Examples:
143 scalariform +spaceBeforeColon -alignParameters -indentSpaces=2 --inPlace foo.scala
144 find . -name '*.scala' | xargs scalariform +rewriteArrowSymbols --verbose --test
145 echo 'class A ( n :Int )' | scalariform
146
5864e14 @mdr Misc README updates, add example library usage code
mdr authored
147 Library
148 -------
149
150 Example usage::
151
152 import scalariform.formatter.preferences._
153 import scalariform.formatter.ScalaFormatter
508a15c @mdr Tweak docs
mdr authored
154 import scalariform.parser.ScalaParserException
5864e14 @mdr Misc README updates, add example library usage code
mdr authored
155
156 object Test extends Application {
157
508a15c @mdr Tweak docs
mdr authored
158 val unformattedScala = """
159 class A {
160 println (42)}"""
161 val preferences = FormattingPreferences().setPreference(IndentSpaces, 3)
162 try {
163 val formattedScala = ScalaFormatter.format(unformattedScala, preferences)
164 println(formattedScala)
165 } catch {
166 case e: ScalaParserException => println("Syntax error in Scala source")
167 }
5864e14 @mdr Misc README updates, add example library usage code
mdr authored
168
169 }
170
1bf9beb @mdr First commit
mdr authored
171 Preferences
172 -----------
173
174 alignParameters
175 ~~~~~~~~~~~~~~~
176
177 Default: ``false``
178
179 Align class/function parameters in the same column. For example, if ``false``, then::
180
181 class Person(name: String,
182 age: Int,
183 birthdate: Date,
184 astrologicalSign: String,
185 shoeSize: Int,
186 favoriteColor: java.awt.Color)
187
188 If ``true``, then::
189
190 class Person(name: String,
191 age: Int,
192 birthdate: Date,
193 astrologicalSign: String,
194 shoeSize: Int,
195 favoriteColor: java.awt.Color)
196
4831dee @mdr Add AlignSingleLineCaseStatements preference to align the arrows of c…
mdr authored
197 alignSingleLineCaseStatements
198 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
199
200 Default: ``false``
201
202 Align the arrows of consecutive single-line case statements. For example, if ``true``, then::
203
204 a match {
205 case b => 1
206 case ccc => 2
207 case dd => 3
208 }
209
210 Is reformatted as::
211
212 a match {
213 case b => 1
214 case ccc => 2
215 case dd => 3
216 }
217
0c60045 @mdr Add an AlignSingleLineCaseStatements.MaxArrowIndent preference to lim…
mdr authored
218 alignSingleLineCaseStatements.maxArrowIndent
219 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
220
221 Default: ``25``
222
223 When using alignSingleLineCaseStatements == true, this is a limit on
224 the number of spaces that can be inserted before an arrow to align it
225 with other case statements. This can be used to avoid very large gaps,
226 e.g.::
227
228 a match {
229 case Some(wibble, wobble) if wibble + wibble > wobble * wibble => 1
230 case ccc => 2
231 }
232
233
1bf9beb @mdr First commit
mdr authored
234 compactStringConcatenation
235 ~~~~~~~~~~~~~~~~~~~~~~~~~~
236
237 Default: ``false``
238
239 Omit spaces when formatting a '+' operator on String literals". For example, If ``false``, then::
240
241 "Hello " + name + "!"
242
243 If ``true``, then::
244
245 "Hello "+name+"!"
246
247 The Scala Style Guide recommends_ that operators, "should `always` be
248 invoked using infix notation with spaces separated the target".
249
250 .. _recommends: http://davetron5000.github.com/scala-style/method_invocation/operators.html
251
252 doubleIndentClassDeclaration
253 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
254
255 Default: ``false``
256
257 With this set to ``true``, class (and trait / object) declarations
258 will be formatted as recommended by the `Scala Style Guide`_. That is,
259 if the declaration section spans multiple lines, it will be formatted
260 so that either the parameter section or the inheritance section is
261 doubly indented. This provides a visual distinction from the members
262 of the class. For example::
263
264 class Person(
265 name: String,
266 age: Int,
267 birthdate: Date,
268 astrologicalSign: String,
269 shoeSize: Int,
270 favoriteColor: java.awt.Color)
271 extends Entity
272 with Logging
273 with Identifiable
274 with Serializable {
275 def firstMethod = ...
276 }
277
278 Or::
279
280 class Person(
281 name: String,
282 age: Int,
283 birthdate: Date,
284 astrologicalSign: String,
285 shoeSize: Int,
286 favoriteColor: java.awt.Color) {
287 def firstMethod = ...
288 }
289
9725596 @mdr Update doc for new arguments
mdr authored
290 formatXml
291 ~~~~~~~~~
292
293 Default: ``true``
294
5160383 @mdr Update docs
mdr authored
295 Format embedded XML literals; if ``false`` they will be left untouched.
9725596 @mdr Update doc for new arguments
mdr authored
296
43f1222 @mdr Add IndentPackageBlocks formatting preference
mdr authored
297 indentPackageBlocks
298 ~~~~~~~~~~~~~~~~~~~
299
300 Default: ``true``
301
302 Whether to indent package blocks. For example, if ``true``::
303
304 package foo {
305 package bar {
306 class Baz
307 }
308 }
309
310 Else if ``false``::
311
312 package foo {
313 package bar {
314 class Baz
315 }
316 }
317
318 indentSpaces
1bf9beb @mdr First commit
mdr authored
319 ~~~~~~~~~~~~
320
321 Default: ``2``
322
323 The number of spaces to use for each level of indentation.
324
325 preserveSpaceBeforeArguments
326 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
327
328 Default: ``false``
329
330 If ``true``, the formatter will keep an existing space before a parenthesis argument. For example::
331
332 stack.pop() should equal (2)
333
334 Otherwise, if ``false``, spaces before arguments will always be removed.
335
336 rewriteArrowSymbols
337 ~~~~~~~~~~~~~~~~~~~
338
339 Default: ``false``
340
341 Replace arrow tokens with their unicode equivalents: ``=>`` with ``⇒``, and ``<-`` with ``←``. For example::
342
343 for (n <- 1 to 10) n % 2 match {
344 case 0 => println("even")
345 case 1 => println("odd")
346 }
347
348 is formatted as::
349
350 for (n ← 1 to 10) n % 2 match {
351 case 0 ⇒ println("even")
352 case 1 ⇒ println("odd")
353 }
354
355 spaceBeforeColon
356 ~~~~~~~~~~~~~~~~
357
358 Default: ``false``
359
360 Whether to ensure a space before colon. For example, If ``false``, then::
361
362 def add(a: Int, b: Int): Int = a + b
363
364 If ``true``, then::
365
366 def add(a : Int, b : Int) : Int = a + b
367
368 Scala Style Guide
369 ~~~~~~~~~~~~~~~~~
370
371 Scalariform is "compatible" with the `Scala Style Guide`_ v1.1.0 in the
372 sense that, given the right preference settings, source code that is
373 initially compiliant with the Style Guide will not become uncompliant
374 after formatting. In a number of cases, running the formatter will
375 make uncompliant source more compliant.
376
377 ============================ ========= =========
378 Preference Value Default?
379 ============================ ========= =========
380 alignParameters ``false``
381 compactStringConcatenation ``false``
382 doubleIndentClassDeclaration ``true`` No
383 indentSpaces ``2``
384 preserveSpaceBeforeArguments ``false``
385 rewriteArrowSymbols ``false``
386 spaceBeforeColon ``false``
387 ============================ ========= =========
388
389 Source directives
390 -----------------
391
392 As well as global preferences, formatting can be tweaked at the source level through comments.
393
394 format: [ON|OFF]
395 ~~~~~~~~~~~~~~~~
396
397 Disables the formatter for selective portions of a source file::
398
399 // format: OFF <-- this directive disables formatting from this point
400 class AsciiDSL {
401 n ¦- "1" -+ { n: Node =>
402 n ¦- "i"
403 n ¦- "ii"
404 n ¦- "iii"
405 n ¦- "iv"
406 n ¦- "v"
407 }
408 n ¦- "2"
409 n ¦- "3" -+ { n: Node =>
410 n ¦- "i"
411 n ¦- "ii" -+ { n: Node =>
412 n ¦- "a"
413 n ¦- "b"
414 n ¦- "c"
415 }
416 n ¦- "iii"
417 n ¦- "iv"
418 n ¦- "v"
419 }
420 // format: ON <-- formatter resumes from this point
421 ...
422 }
423 // (see: http://dev.day.com/microsling/content/blogs/main/scalajcr2.html)
424
425 format: [+|-]<preferenceName>
426 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
427
428 Sets a preference for the entire of the source file, overriding the global formatting settings::
429
430 // format: +preserveSpaceBeforeArguments
431 class StackSpec extends FlatSpec with ShouldMatchers {
432 // ...
433 stack.pop() should equal (2)
434 }
Something went wrong with that request. Please try again.