Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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