Change dataset name
[jalview.git] / utils / jalopy / docs / separation.html
1
2     <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
3   <html><head>
4       <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
5    <title>4.3.5.&nbsp;Blank Lines</title><link rel="stylesheet" href="site.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="manual.html" title="Jalopy User Manual"><link rel="up" href="printer.html" title="4.3.&nbsp;Printer"><link rel="previous" href="wrapping.html" title="4.3.4.&nbsp;Wrapping"><link rel="next" href="comments.html" title="4.3.6.&nbsp;Comments"><link rel="preface" href="dedication.html" title="Dedication"><link rel="preface" href="acknowledge.html" title="Acknowledgements"><link rel="preface" href="introduction.html" title="Introduction"><link rel="part" href="part-core.html" title="Part&nbsp;I.&nbsp;Jalopy core"><link rel="chapter" href="installation.html" title="Chapter&nbsp;1.&nbsp;Installation"><link rel="chapter" href="build.html" title="Chapter&nbsp;2.&nbsp;Building"><link rel="chapter" href="usage.html" title="Chapter&nbsp;3.&nbsp;Usage"><link rel="chapter" href="settings.html" title="Chapter&nbsp;4.&nbsp;Settings"><link rel="part" href="part-plugins.html" title="Part&nbsp;II.&nbsp;Plug-ins"><link rel="chapter" href="plugin-ant.html" title="Chapter&nbsp;5.&nbsp;Ant Plug-in task"><link rel="chapter" href="plugin-console.html" title="Chapter&nbsp;6.&nbsp;Console Application"><link rel="chapter" href="plugin-eclipse.html" title="Chapter&nbsp;7.&nbsp;Eclipse Plug-in"><link rel="chapter" href="plugin-jbuilder.html" title="Chapter&nbsp;8.&nbsp;JBuilder OpenTool"><link rel="chapter" href="plugin-jdev.html" title="Chapter&nbsp;9.&nbsp;JDeveloper Extension"><link rel="chapter" href="plugin-jedit.html" title="Chapter&nbsp;10.&nbsp;jEdit Plug-in"><link rel="chapter" href="plugin-netbeans.html" title="Chapter&nbsp;11.&nbsp;NetBeans/Sun ONE Studio module"><link rel="appendix" href="dependencies.html" title="Appendix&nbsp;A.&nbsp;Library Dependencies"><link rel="appendix" href="license-bsd.html" title="Appendix&nbsp;B.&nbsp;The Jalopy BSD License"><link rel="appendix" href="license-antlr.html" title="Appendix&nbsp;C.&nbsp;ANTLR SOFTWARE RIGHTS"><link rel="appendix" href="license-apache.html" title="Appendix&nbsp;D.&nbsp;The Apache Software License, Version 1.1"><link rel="appendix" href="license-gnu.html" title="Appendix&nbsp;E.&nbsp;GNU GENERAL PUBLIC LICENSE Version 2, June 1991"><link rel="appendix" href="license-gnu-doc.html" title="Appendix&nbsp;F.&nbsp;GNU Free Documentation License Version 1.1, March 2000"><link rel="appendix" href="license-common-public.html" title="Appendix&nbsp;G.&nbsp;Common Public License Version 1.0"><link rel="appendix" href="license-sun-public.html" title="Appendix&nbsp;H.&nbsp;SUN PUBLIC LICENSE Version 1.0"><link rel="index" href="ix01.html" title="Index"><link rel="subsection" href="separation.html#separation-blank-lines" title="4.3.5.1.&nbsp;General"><link rel="subsection" href="separation.html#separation-misc" title="4.3.5.2.&nbsp;Misc"><link rel="subsection" href="separation.html#separation-comment" title="4.3.5.3.&nbsp;Comments">
6       <meta name="description" content="Jalopy Java Source Code Formatter Beautifier Pretty Printer"> 
7       <meta http-equiv="pics-label" content='(pics-1.1 "http://www.icra.org/ratingsv02.html" l gen true for "http://jalopy.sf.net" r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true for "http://jalopy.sf.net" r (n 0 s 0 v 0 l 0))'> 
8     </head><body id="toppage" bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table width="700" border="0" cellpadding="0" cellspacing="0" align="left"><tbody><tr><td><table cellpadding="0" cellspacing="0" width="100%" style="border:1px solid #336699"><tbody><tr><td height="16"></td></tr><tr><td bgcolor="#3399cc" height="1"></td></tr><tr style="border:none"><td style="border:none"><table border="0" cellspacing="0" cellpadding="0"><tbody><tr><td class="logo">JALOPY</td><td class="sublogo" valign="bottom">Java Source Code Formatter Beautifier Pretty Printer</td></tr></tbody></table></td></tr><tr><td bgcolor="#3399cc" height="1"></td></tr><tr><td height="10"></td></tr><tr><td bgcolor="#ff8000" height="4"></td></tr><tr><td height="20" bgcolor="#336699" style="color:#ffffff;padding-left:10px"><a href="./index.html" class="navlink">Overview</a> &#149;
9                     <a href="./download.html" class="navlink">Download</a> &#149;
10                     <a href="./docs.html" class="navlink">Documentation</a> &#149;
11                     <a href="./plugins.html" class="navlink">Plug-ins</a> &#149;
12                     <a href="./links.html" class="navlink">Links</a> &#149;
13                     <a href="./contact.html" class="navlink">Contact</a></td></tr><tr><td height="1" bgcolor="#ffffff"></td></tr></tbody></table></td></tr><tr valign="top"><td valign="top" bgcolor="#ffffff"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tbody><tr><td height="20" bgcolor="#faebd7" style="padding-left:15px"><a href="./features.html" class="navlink2">Features</a> |
14                     <a href="./history.html" class="navlink2">History</a> |
15                     <a href="./manual.html" class="navlink2">Manual</a> |
16                     <a href="./faq.html" class="navlink2">FAQ</a> |
17                     <a href="./api/index.html" class="navlink2">Javadoc</a></td></tr><tr><td height="20" bgcolor="#ffffff"></td></tr><tr><td bgcolor="#eeeecc" height="17" align="right" style="font-size:10px;padding-right:3px">
18                     This page generated: <strong>June 8 2004</strong></td></tr></tbody></table><table border="0" width="100%" cellspacing="0" cellpadding="5"><tr><td><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.3.5.&nbsp;Blank Lines</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="wrapping.html">Prev</a>&nbsp;</td><th width="60%" align="center">4.3.&nbsp;Printer</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="comments.html">Next</a></td></tr></table><hr></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="separation"></a>4.3.5.&nbsp;Blank Lines</h3></div></div><div></div></div><p>
19 Controls the Jalopy Blank Lines settings: the insertion of blank lines to
20 separate statements or declarations with different functions or meanings.
21 </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="separation-blank-lines"></a>4.3.5.1.&nbsp;General</h4></div></div><div></div></div><p>
22 Lets you specify the general blank lines sizes for different Java source file elements.
23 </p><div class="itemizedlist"><ul type="disc"><li><p><a name="blank-lines-package"></a>
24 Package statement
25 </p><a class="indexterm" name="d0e3379"></a><a class="indexterm" name="d0e3382"></a><p>
26 Lets you control how many blank lines should be printed after the package statement.
27 </p><div class="example"><a name="ex-blank-lines-package"></a><p class="title"><b>Example&nbsp;4.115.&nbsp;3 Blank lines after package statement</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">package de.hunsicker.jalopy.printer;
28 &lt;--
29 &lt;--
30 &lt;--
31 import antlr.collections.AST;
32
33 import de.hunsicker.jalopy.parser.JavaAST;
34 import de.hunsicker.jalopy.parser.JavaTokenTypes;
35
36 ...
37 </pre></td></tr></table></div><p></p></li><li><p><a name="blank-lines-import"></a>
38 Last import statement
39 </p><a class="indexterm" name="d0e3398"></a><a class="indexterm" name="d0e3401"></a><p>
40 Lets you control how many blank lines should be printed after the last import statement.
41 </p><div class="example"><a name="ex-blank-lines-import"></a><p class="title"><b>Example&nbsp;4.116.&nbsp;4 Blank lines after last import statement</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">package de.hunsicker.jalopy.printer;
42
43 import antlr.collections.AST;
44
45 import de.hunsicker.jalopy.parser.JavaAST;
46 import de.hunsicker.jalopy.parser.JavaTokenTypes;
47 &lt;--
48 &lt;--
49 &lt;--
50 &lt;--
51 public class Printer
52 {
53     ...
54 }
55 </pre></td></tr></table></div><p></p></li><li><p><a name="blank-lines-classes"></a>
56 Classes
57 </p><a class="indexterm" name="d0e3417"></a><a class="indexterm" name="d0e3420"></a><p>
58 Lets you control how many blank lines should be printed between two
59 class declarations.
60 </p><div class="example"><a name="blank-lines-class"></a><p class="title"><b>Example&nbsp;4.117.&nbsp;2 Blank lines between two class declarations</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">class One
61 {
62     ...
63 }
64 &lt;--
65 &lt;--
66 class Two
67 {
68     ...
69 }
70 </pre></td></tr></table></div><p></p></li><li><p><a name="blank-lines-interfaces"></a>
71 Interfaces
72 </p><a class="indexterm" name="d0e3436"></a><a class="indexterm" name="d0e3439"></a><p>
73 Lets you control how many blank lines should be printed between two
74 interface declarations.
75 </p><div class="example"><a name="blank-lines-ifc"></a><p class="title"><b>Example&nbsp;4.118.&nbsp;3 Blank lines between two interface declarations</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">interface One
76 {
77     ...
78 }
79 &lt;--
80 &lt;--
81 &lt;--
82 interface Two
83 {
84     ...
85 }
86 </pre></td></tr></table></div><p></p></li><li><p><a name="blank-lines-methods"></a>
87 Methods
88 </p><a class="indexterm" name="d0e3455"></a><a class="indexterm" name="d0e3458"></a><p>
89 Lets you control how many blank lines should be printed between two
90 method/constructor declarations.
91 </p><div class="example"><a name="blank-lines-method"></a><p class="title"><b>Example&nbsp;4.119.&nbsp;3 Blank lines between two method declarations</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">public static Printer getInstance()
92 {
93     return INSTANCE;
94 }
95 &lt;--
96 &lt;--
97 &lt;--
98 public void print(AST node, ASTWriter out)
99            throws IOException
100 {
101     ...
102 }
103 </pre></td></tr></table></div><p></p></li><li><p><a name="blank-lines-blocks"></a>
104 Blocks
105 </p><a class="indexterm" name="d0e3474"></a><a class="indexterm" name="d0e3477"></a><p>
106 Lets you control how many blank lines should be printed before and after
107 statement blocks (if-else , for, while, do-while, switch, try-catch-finally, synchronized).
108 Note that the 'Blank lines after' setting also applies for anonymous inner classes.
109 </p><div class="example"><a name="ex-blank-lines-blocks"></a><p class="title"><b>Example&nbsp;4.120.&nbsp;2 Blank lines between before and after blocks</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">AST type = null;
110 &lt;--
111 &lt;--
112 switch (next.getType())
113 {
114     case JavaTokenTypes.LPAREN :
115         type = PrinterUtils.advanceToFirstNonParen(next);
116         break;
117     default :
118         type = next;
119         break;
120 }
121 &lt;--
122 &lt;--
123 AST ident = type.getFirstChild();
124 </pre></td></tr></table></div><p></p></li><li><p><a name="blank-lines-declarations"></a>
125 Declarations
126 </p><a class="indexterm" name="d0e3493"></a><a class="indexterm" name="d0e3496"></a><p>
127 Lets you control how many blank lines should be printed before and after
128 variable declarations.
129 </p></li><li><p><a name="blank-lines-case"></a>
130 Case blocks
131 </p><a class="indexterm" name="d0e3506"></a><a class="indexterm" name="d0e3509"></a><p>
132 Lets you control how many blank lines should be printed before each case
133 block of a switch expression.
134 </p><div class="example"><a name="ex-blank-lines-case"></a><p class="title"><b>Example&nbsp;4.121.&nbsp;3 Blank lines before case blocks</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">switch (next.getType())
135 {
136 &lt;--
137 &lt;--
138 &lt;--
139     case JavaTokenTypes.LPAREN :
140         type = PrinterUtils.advanceToFirstNonParen(next);
141         break;
142 &lt;--
143 &lt;--
144 &lt;--
145     default :
146         type = next;
147         break;
148 }
149 </pre></td></tr></table></div><p></p></li><li><p><a name="blank-lines-control"></a>
150 Control statements
151 </p><a class="indexterm" name="d0e3525"></a><a class="indexterm" name="d0e3528"></a><p>
152 Lets you control how many blank lines should be printed before the statements
153 <span><b class="command">return</b></span>, <span><b class="command">break</b></span> and <span><b class="command">continue</b></span>.
154 </p><div class="example"><a name="ex-blank-lines-control"></a><p class="title"><b>Example&nbsp;4.122.&nbsp;2 Blank lines before case control statements</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">switch (next.getType())
155 {
156     case JavaTokenTypes.LPAREN :
157         type = PrinterUtils.advanceToFirstNonParen(next);
158 &lt;--
159 &lt;--
160         break;
161
162     default :
163         type = next;
164 &lt;--
165 &lt;--
166         break;
167 }
168 </pre></td></tr></table></div><p></p></li><li><p><a name="blank-lines-sl-comments"></a>
169 Single-line comments
170 </p><a class="indexterm" name="d0e3553"></a><a class="indexterm" name="d0e3556"></a><p>
171 Lets you control how many blank lines should be printed before single-line
172 comments.
173 </p></li><li><p><a name="blank-lines-ml-comments"></a>
174 Multi-line comments
175 </p><a class="indexterm" name="d0e3566"></a><a class="indexterm" name="d0e3569"></a><p>
176 Lets you control how many blank lines should be printed before multi-line
177 comments.
178 </p></li><li><p><a name="blank-lines-javadoc"></a>
179 Javadoc comments
180 </p><a class="indexterm" name="d0e3579"></a><a class="indexterm" name="d0e3582"></a><p>
181 Lets you control how many blank lines should be printed before Javadoc
182 comments.
183 </p></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="separation-misc"></a>4.3.5.2.&nbsp;Misc</h4></div></div><div></div></div><p>Lets you control miscellaneous separation settings.</p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3594"></a>4.3.5.2.1.&nbsp;Misc</h5></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a name="separation-misc-left-curly"></a>
184 Blank lines after left curly brace
185 </p><a class="indexterm" name="d0e3601"></a><a class="indexterm" name="d0e3604"></a><p>
186 Forces the given number of blank lines after left curly braces no matter
187 what your other blank lines settings say.
188 </p><div class="example"><a name="ex-separation-before-blocks"></a><p class="title"><b>Example&nbsp;4.123.&nbsp;Blank lines before blocks=1</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">public void foo()
189 {
190 &lt;--
191     if (condition())
192     {
193 &lt;--
194         if (anotherCondition())
195         {
196             doSomething();
197         }
198     }
199 }
200 </pre></td></tr></table></div><p></p><div class="example"><a name="ex-separation-misc-left-curly-yes"></a><p class="title"><b>Example&nbsp;4.124.&nbsp;Blank lines before blocks=1, Blank lines after left curly braces=0</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">public void foo()
201 {
202     if (condition())
203     {
204         if (anotherCondition())
205         {
206             doSomething();
207         }
208     }
209 }
210 </pre></td></tr></table></div><p></p></li><li><p><a name="separation-misc-right-curly"></a>
211 Blank lines before right curly brace
212 </p><a class="indexterm" name="d0e3626"></a><a class="indexterm" name="d0e3629"></a><p>
213 Forces the given number of blank lines before closing curly braces no matter
214 what your other blank lines settings say.
215 </p><div class="example"><a name="ex-separation-misc-left-curly-no"></a><p class="title"><b>Example&nbsp;4.125.&nbsp;Blank lines before blocks=1</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">public void foo()
216 {
217     if (condititon())
218     {
219         if (anotherCondition())
220         {
221             doSomething();
222 &lt;--
223         }
224 &lt;--
225     }
226 &lt;--
227 }
228 </pre></td></tr></table></div><p></p></li><li><p><a name="separation-misc-keep"></a>
229 Keep Blank lines up to
230 </p><p>
231 If enabled, retains up to the given number of blank lines found in the
232 original source. This only works for method or constructor bodies. Note that Jalopy
233 still takes your other blank lines settings into account.
234 </p><div class="example"><a name="ex-separation-misc-keep-no"></a><p class="title"><b>Example&nbsp;4.126.&nbsp;Source code with blank lines to separate code sections</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">aMVString = new MultiValueString("abc");
235 &lt;--
236 System.out.println("MV = "+aMVString);
237 &lt;--
238 System.out.println("MV0 = "+aMVString.extract(0));
239 System.out.println("MV1 = "+aMVString.extract(1));
240 System.out.println("MV2 = "+aMVString.extract(2));
241 System.out.println("");
242 </pre></td></tr></table></div><p>
243 If this feature is left disabled, Jalopy will print the individual lines according
244 to the current blank lines settings but won't try to retain any blank lines.
245 </p></li></ul></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="chunks"></a>4.3.5.2.2.&nbsp;Chunks</h5></div></div><div></div></div><a class="indexterm" name="d0e3657"></a><p>
246 Lets you define what makes a chunk: a section of associated statements.
247 </p><div class="itemizedlist"><ul type="disc"><li><p><a name="chunks-comments"></a>
248 By comments
249 </p><a class="indexterm" name="d0e3666"></a><a class="indexterm" name="d0e3669"></a><p>
250 If enabled, a statement with a comment before is recognized as the start of a new
251 chunk.
252 </p><div class="example"><a name="ex-chunks-comments"></a><p class="title"><b>Example&nbsp;4.127.&nbsp;Aligning variable declarations</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">
253 String        text  = "text";
254 int           a     = -1;
255
256 // create a new entry
257 History.Entry entry = new History.Entry(text);
258 </pre></td></tr></table></div><p></p><div class="example"><a name="ex-chunks-comments-enabled"></a><p class="title"><b>Example&nbsp;4.128.&nbsp;Aligning variable declarations with chunking by comments</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">
259 String text  = "text";
260 int    a     = -1;
261
262 // create a new entry
263 History.Entry entry = new History.Entry(text);
264 </pre></td></tr></table></div><p></p></li><li><p><a name="chunks-blank-lines"></a>
265 By Blank lines
266 </p><a class="indexterm" name="d0e3691"></a><a class="indexterm" name="d0e3694"></a><p>
267 If enabled, a statement which has one or more blank lines before is recognized
268 as the start of a new chunk.
269 </p></li></ul></div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="separation-comment"></a>4.3.5.3.&nbsp;Comments</h4></div></div><div></div></div><p>
270 Lets you control the behaviour of the separator comments. If the
271 <a href="sorting.html" title="4.3.12.&nbsp;Sorting">sorting of class elements</a> is enabled, Separator comments
272 can be inserted before every element section, to make it easier to identify the
273 different parts of a source file.
274 </p><a class="indexterm" name="d0e3709"></a><div class="example"><a name="ex-separation-comment"></a><p class="title"><b>Example&nbsp;4.129.&nbsp;Separator comment</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">
275 //~ Methods ------------------------------------------------------------------
276 </pre></td></tr></table></div><p></p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3718"></a>4.3.5.3.1.&nbsp;General</h5></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
277 Add separator comments
278 </p><p>
279 Enables the insertions of separator comments.
280 </p></li><li><p>
281 Add separator comments for inner classes
282 </p><p>
283 The insertion of separator comments for inner classes/interfaces may lead to
284 confusion, therefore you can control it here separately.
285 </p></li></ul></div></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3732"></a>4.3.5.3.2.&nbsp;Descriptions</h5></div></div><div></div></div><p>Lets you define the description text for each of the different class elements.</p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d0e3737"></a>4.3.5.3.3.&nbsp;Fill character</h5></div></div><div></div></div><p>Lets you define the fill character for the comments.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="wrapping.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="printer.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="comments.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.3.4.&nbsp;Wrapping&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;4.3.6.&nbsp;Comments</td></tr></table></div></td></tr></table></td></tr><tr><td bgcolor="#eeeecc" height="17" style="font-size:9px;padding-left:5px"><a href="#toppage">to top</a></td></tr><tr><td height="30"><br></td></tr><tr><td height="3"></td></tr><tr><td bgcolor="#336699" height="1"></td></tr><tr><td height="1"></td></tr><tr><td bgcolor="#336699" height="16"></td></tr><tr><td bgcolor="#ff9966" height="4"></td></tr><tr><td class="footer" align="center" height="15" valign="middle">
286             Copyright &copy; 2001-2004, <a class="footer" href="./contact.html">Marco Hunsicker</a>. All rights reserved. Hosted by <a href="http://sourceforge.net">SourceForge.net</a></td></tr></tbody></table><img src="http://sourceforge.net/sflogo.php?group_id=45216&amp;type=1" width="1" height="1" border="0" hspace="0" vspace="0" alt=""></body></html>