Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 326 lines (230 sloc) 9.347 kb
1bf9beb @mdr First commit
authored
1 Scalariform
2 ===========
3
5864e14 @mdr 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
5 stand-alone command line tool, with integrations for Eclipse, TextMate
6 and sbt. Currently, Scalariform supports only a limited set of
cb9b2ad @mdr Tweaks for command line tool
authored
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
6c71e0b @mdr Note ENSIME integration in docs
authored
16 Integration with Eclipse
17 ------------------------
1bf9beb @mdr First commit
authored
18
5864e14 @mdr Misc README updates, add example library usage code
authored
19 Scala IDE for Eclipse uses Scalariform for formatting:
1bf9beb @mdr First commit
authored
20
56bbcfb @mdr Update README for Eclipse, TextMate integrations
authored
21 http://download.scala-ide.org/
1bf9beb @mdr First commit
authored
22
56bbcfb @mdr Update README for Eclipse, TextMate integrations
authored
23 (See http://www.assembla.com/wiki/show/scala-ide/Requirements_and_Installation
24 for more detailed instructions.)
1bf9beb @mdr First commit
authored
25
5160383 @mdr Update docs
authored
26 Formatting works the same in the Scala editor; that is, either
1bf9beb @mdr First commit
authored
27
5160383 @mdr Update docs
authored
28 - Right click in the editor -> Source -> Format
29 - Press Ctrl-Shift-F
1bf9beb @mdr First commit
authored
30
5160383 @mdr Update docs
authored
31 To configure preferences, go to Window -> Preferences -> Scala -> Formatter
1bf9beb @mdr First commit
authored
32
5160383 @mdr Update docs
authored
33 It can also perform formatting as a save action (Window -> Preferences -> Java -> Editor -> Save Actions).
1bf9beb @mdr First commit
authored
34
6c71e0b @mdr Note ENSIME integration in docs
authored
35 Integration with ENSIME
36 -----------------------
56bbcfb @mdr Update README for Eclipse, TextMate integrations
authored
37
6c71e0b @mdr Note ENSIME integration in docs
authored
38 "`ENSIME`_ uses the Scalariform library to format Scala sources. Type C-c f to format the current buffer."
56bbcfb @mdr Update README for Eclipse, TextMate integrations
authored
39
6c71e0b @mdr Note ENSIME integration in docs
authored
40 http://aemon.com/file_dump/ensime_manual.html#tth_sEc4.8
56bbcfb @mdr Update README for Eclipse, TextMate integrations
authored
41
6c71e0b @mdr Note ENSIME integration in docs
authored
42 .. _ENSIME: http://github.com/aemoncannon/ensime
56bbcfb @mdr Update README for Eclipse, TextMate integrations
authored
43
44 Integration with sbt
45 --------------------
46
47 `sbt-scalariform`_, written by Olivier Michallat, provides an sbt plugin contributing formatting actions.
48
49 .. _sbt-scalariform: http://github.com/olim7t/sbt-scalariform
50
6c71e0b @mdr Note ENSIME integration in docs
authored
51 Integration with TextMate
52 -------------------------
53
8ba9dd0 @mdr Tweak a link in README
authored
54 See Mads Jensen's Scala TextMate bundle:
6c71e0b @mdr Note ENSIME integration in docs
authored
55
56 http://github.com/mads379/scala.tmbundle
57
58 Reformat using Ctrl-Shift-H.
59
cb9b2ad @mdr Tweaks for command line tool
authored
60 Command line tool
61 -----------------
62
5864e14 @mdr Misc README updates, add example library usage code
authored
63 Scalariform includes a stand-alone command line utility. Sample script::
cb9b2ad @mdr Tweaks for command line tool
authored
64
65 #!/bin/bash
66 scala -cp /path/to/scalariform-X.Y.Z.jar scalariform.commandline.Main "$@"
67
68 Usage::
69
70 scalariform [options] [files...]
71
72 Options:
436edff @olim7t New commandline option to provide a file containing the list of sources ...
olim7t authored
73 --help, -h Show help
74 --inPlace, -i Replace the input file(s) in place with a formatted version.
75 --test, -t Check the input(s) to see if they are correctly formatted, return a non-zero error code if not.
76 --fileList=<path>, -l=<path> Read the list of input file(s) from a text file (one per line)
77 --verbose -v Verbose output
cb9b2ad @mdr Tweaks for command line tool
authored
78
79 Preferences:
80 [+|-]alignParameters Enable/disable Align parameters on different lines in the same column
81 [+|-]compactStringConcatenation Enable/disable Omit spaces when formatting a '+' operator on String literals
82 [+|-]doubleIndentClassDeclaration Enable/disable Double indent either a class's parameters or its inheritance list
9725596 @mdr Update doc for new arguments
authored
83 [+|-]formatXml Enable/disable Format XML literals
cb9b2ad @mdr Tweaks for command line tool
authored
84 -indentSpaces=[1-10] Set Number of spaces to use for indentation
85 [+|-]preserveSpaceBeforeArguments Enable/disable Preserve a space before a parenthesis argument
86 [+|-]rewriteArrowSymbols Enable/disable Replace arrow tokens with unicode equivalents: => with ⇒, and <- with ←
87 [+|-]spaceBeforeColon Enable/disable Add a space before colons
88
89 Examples:
90 scalariform +spaceBeforeColon -alignParameters -indentSpaces=2 --inPlace foo.scala
91 find . -name '*.scala' | xargs scalariform +rewriteArrowSymbols --verbose --test
92 echo 'class A ( n :Int )' | scalariform
93
5864e14 @mdr Misc README updates, add example library usage code
authored
94
95 Library
96 -------
97
98 Example usage::
99
100 import scalariform.formatter.preferences._
101 import scalariform.formatter.ScalaFormatter
102
103 object Test extends Application {
104
105 val unformattedScala = """
106 class A {
107 println (42)}"""
108 val preferences = FormattingPreferences().setPreference(IndentSpaces, 3)
109 val formattedScala = ScalaFormatter.format(unformattedScala, preferences)
110 println(formattedScala)
111
112 }
113
114 Maven (using sbt)::
115
116 val scalaToolsSnapshots = "Scala-Tools Maven2 Snapshots Repository" at "http://scala-tools.org/repo-snapshots"
117 val scalariform = "org.scalariform" %% "scalariform" % "0.0.5-SNAPSHOT"
118
119
1bf9beb @mdr First commit
authored
120 Preferences
121 -----------
122
123 alignParameters
124 ~~~~~~~~~~~~~~~
125
126 Default: ``false``
127
128 Align class/function parameters in the same column. For example, if ``false``, then::
129
130 class Person(name: String,
131 age: Int,
132 birthdate: Date,
133 astrologicalSign: String,
134 shoeSize: Int,
135 favoriteColor: java.awt.Color)
136
137 If ``true``, then::
138
139 class Person(name: String,
140 age: Int,
141 birthdate: Date,
142 astrologicalSign: String,
143 shoeSize: Int,
144 favoriteColor: java.awt.Color)
145
146 compactStringConcatenation
147 ~~~~~~~~~~~~~~~~~~~~~~~~~~
148
149 Default: ``false``
150
151 Omit spaces when formatting a '+' operator on String literals". For example, If ``false``, then::
152
153 "Hello " + name + "!"
154
155 If ``true``, then::
156
157 "Hello "+name+"!"
158
159 The Scala Style Guide recommends_ that operators, "should `always` be
160 invoked using infix notation with spaces separated the target".
161
162 .. _recommends: http://davetron5000.github.com/scala-style/method_invocation/operators.html
163
164 doubleIndentClassDeclaration
165 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
166
167 Default: ``false``
168
169 With this set to ``true``, class (and trait / object) declarations
170 will be formatted as recommended by the `Scala Style Guide`_. That is,
171 if the declaration section spans multiple lines, it will be formatted
172 so that either the parameter section or the inheritance section is
173 doubly indented. This provides a visual distinction from the members
174 of the class. For example::
175
176 class Person(
177 name: String,
178 age: Int,
179 birthdate: Date,
180 astrologicalSign: String,
181 shoeSize: Int,
182 favoriteColor: java.awt.Color)
183 extends Entity
184 with Logging
185 with Identifiable
186 with Serializable {
187 def firstMethod = ...
188 }
189
190 Or::
191
192 class Person(
193 name: String,
194 age: Int,
195 birthdate: Date,
196 astrologicalSign: String,
197 shoeSize: Int,
198 favoriteColor: java.awt.Color) {
199 def firstMethod = ...
200 }
201
9725596 @mdr Update doc for new arguments
authored
202 formatXml
203 ~~~~~~~~~
204
205 Default: ``true``
206
5160383 @mdr Update docs
authored
207 Format embedded XML literals; if ``false`` they will be left untouched.
9725596 @mdr Update doc for new arguments
authored
208
1bf9beb @mdr First commit
authored
209 indentSpaces
210 ~~~~~~~~~~~~
211
212 Default: ``2``
213
214 The number of spaces to use for each level of indentation.
215
216 preserveSpaceBeforeArguments
217 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
218
219 Default: ``false``
220
221 If ``true``, the formatter will keep an existing space before a parenthesis argument. For example::
222
223 stack.pop() should equal (2)
224
225 Otherwise, if ``false``, spaces before arguments will always be removed.
226
227 rewriteArrowSymbols
228 ~~~~~~~~~~~~~~~~~~~
229
230 Default: ``false``
231
232 Replace arrow tokens with their unicode equivalents: ``=>`` with ``⇒``, and ``<-`` with ``←``. For example::
233
234 for (n <- 1 to 10) n % 2 match {
235 case 0 => println("even")
236 case 1 => println("odd")
237 }
238
239 is formatted as::
240
241 for (n ← 1 to 10) n % 2 match {
242 case 0 ⇒ println("even")
243 case 1 ⇒ println("odd")
244 }
245
246 spaceBeforeColon
247 ~~~~~~~~~~~~~~~~
248
249 Default: ``false``
250
251 Whether to ensure a space before colon. For example, If ``false``, then::
252
253 def add(a: Int, b: Int): Int = a + b
254
255 If ``true``, then::
256
257 def add(a : Int, b : Int) : Int = a + b
258
259 Scala Style Guide
260 ~~~~~~~~~~~~~~~~~
261
262 Scalariform is "compatible" with the `Scala Style Guide`_ v1.1.0 in the
263 sense that, given the right preference settings, source code that is
264 initially compiliant with the Style Guide will not become uncompliant
265 after formatting. In a number of cases, running the formatter will
266 make uncompliant source more compliant.
267
268 ============================ ========= =========
269 Preference Value Default?
270 ============================ ========= =========
271 alignParameters ``false``
272 compactStringConcatenation ``false``
273 doubleIndentClassDeclaration ``true`` No
274 indentSpaces ``2``
275 preserveSpaceBeforeArguments ``false``
276 rewriteArrowSymbols ``false``
277 spaceBeforeColon ``false``
278 ============================ ========= =========
279
280 Source directives
281 -----------------
282
283 As well as global preferences, formatting can be tweaked at the source level through comments.
284
285 format: [ON|OFF]
286 ~~~~~~~~~~~~~~~~
287
288 Disables the formatter for selective portions of a source file::
289
290 // format: OFF <-- this directive disables formatting from this point
291 class AsciiDSL {
292 n ¦- "1" -+ { n: Node =>
293 n ¦- "i"
294 n ¦- "ii"
295 n ¦- "iii"
296 n ¦- "iv"
297 n ¦- "v"
298 }
299 n ¦- "2"
300 n ¦- "3" -+ { n: Node =>
301 n ¦- "i"
302 n ¦- "ii" -+ { n: Node =>
303 n ¦- "a"
304 n ¦- "b"
305 n ¦- "c"
306 }
307 n ¦- "iii"
308 n ¦- "iv"
309 n ¦- "v"
310 }
311 // format: ON <-- formatter resumes from this point
312 ...
313 }
314 // (see: http://dev.day.com/microsling/content/blogs/main/scalajcr2.html)
315
316 format: [+|-]<preferenceName>
317 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
318
319 Sets a preference for the entire of the source file, overriding the global formatting settings::
320
321 // format: +preserveSpaceBeforeArguments
322 class StackSpec extends FlatSpec with ShouldMatchers {
323 // ...
324 stack.pop() should equal (2)
325 }
Something went wrong with that request. Please try again.