Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "PERLTIDY 1" | |
132 | .TH PERLTIDY 1 "2003-10-22" "perl v5.8.0" "User Contributed Perl Documentation" | |
133 | .SH "NAME" | |
134 | perltidy \- a perl script indenter and reformatter | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | .Vb 5 | |
138 | \& perltidy [ options ] file1 file2 file3 ... | |
139 | \& (output goes to file1.tdy, file2.tdy, file3.tdy, ...) | |
140 | \& perltidy [ options ] file1 -o outfile | |
141 | \& perltidy [ options ] file1 -st >outfile | |
142 | \& perltidy [ options ] <infile >outfile | |
143 | .Ve | |
144 | .SH "DESCRIPTION" | |
145 | .IX Header "DESCRIPTION" | |
146 | Perltidy reads a perl script and writes an indented, reformatted script. | |
147 | .PP | |
148 | Many users will find enough information in \*(L"\s-1EXAMPLES\s0\*(R" to get | |
149 | started. New users may benefit from the short tutorial | |
150 | which can be found at | |
151 | http://perltidy.sourceforge.net/tutorial.html | |
152 | .PP | |
153 | A convenient aid to systematically defining a set of style parameters | |
154 | can be found at | |
155 | http://perltidy.sourceforge.net/stylekey.html | |
156 | .PP | |
157 | Perltidy can produce output on either of two modes, depending on the | |
158 | existence of an \fB\-html\fR flag. Without this flag, the output is passed | |
159 | through a formatter. The default formatting tries to follow the | |
160 | recommendations in \fIperlstyle\fR\|(1), but it can be controlled in detail with | |
161 | numerous input parameters, which are described in \*(L"\s-1FORMATTING\s0 \s-1OPTIONS\s0\*(R". | |
162 | .PP | |
163 | When the \fB\-html\fR flag is given, the output is passed through an \s-1HTML\s0 | |
164 | formatter which is described in \*(L"\s-1HTML\s0 \s-1OPTIONS\s0\*(R". | |
165 | .SH "EXAMPLES" | |
166 | .IX Header "EXAMPLES" | |
167 | .Vb 1 | |
168 | \& perltidy somefile.pl | |
169 | .Ve | |
170 | .PP | |
171 | This will produce a file \fIsomefile.pl.tdy\fR containing the script reformatted | |
172 | using the default options, which approximate the style suggested in | |
173 | \&\fIperlstyle\fR\|(1). Perltidy never changes the input file. | |
174 | .PP | |
175 | .Vb 1 | |
176 | \& perltidy *.pl | |
177 | .Ve | |
178 | .PP | |
179 | Execute perltidy on all \fI.pl\fR files in the current directory with the | |
180 | default options. The output will be in files with an appended \fI.tdy\fR | |
181 | extension. For any file with an error, there will be a file with extension | |
182 | \&\fI.ERR\fR. | |
183 | .PP | |
184 | .Vb 1 | |
185 | \& perltidy -b file1.pl file2.pl | |
186 | .Ve | |
187 | .PP | |
188 | Modify \fIfile1.pl\fR and \fIfile1.pl\fR in place, and backup the originals to | |
189 | \&\fIfile1.pl.bak\fR and \fIfile2.pl.bak\fR. If \fIfile1.pl.bak\fR and/or \fIfile2.pl.bak\fR | |
190 | already exist, they will be overwritten. | |
191 | .PP | |
192 | .Vb 1 | |
193 | \& perltidy -gnu somefile.pl | |
194 | .Ve | |
195 | .PP | |
196 | Execute perltidy on file \fIsomefile.pl\fR with a style which approximates the | |
197 | \&\s-1GNU\s0 Coding Standards for C programs. The output will be \fIsomefile.pl.tdy\fR. | |
198 | .PP | |
199 | .Vb 1 | |
200 | \& perltidy -i=3 somefile.pl | |
201 | .Ve | |
202 | .PP | |
203 | Execute perltidy on file \fIsomefile.pl\fR, with 3 columns for each level of | |
204 | indentation (\fB\-i=3\fR) instead of the default 4 columns. There will not be any | |
205 | tabs in the reformatted script, except for any which already exist in comments, | |
206 | pod documents, quotes, and here documents. Output will be \fIsomefile.pl.tdy\fR. | |
207 | .PP | |
208 | .Vb 1 | |
209 | \& perltidy -i=3 -et=8 somefile.pl | |
210 | .Ve | |
211 | .PP | |
212 | Same as the previous example, except that leading whitespace will | |
213 | be entabbed with one tab character per 8 spaces. | |
214 | .PP | |
215 | .Vb 1 | |
216 | \& perltidy -ce -l=72 somefile.pl | |
217 | .Ve | |
218 | .PP | |
219 | Execute perltidy on file \fIsomefile.pl\fR with all defaults except use \*(L"cuddled | |
220 | elses\*(R" (\fB\-ce\fR) and a maximum line length of 72 columns (\fB\-l=72\fR) instead of | |
221 | the default 80 columns. | |
222 | .PP | |
223 | .Vb 1 | |
224 | \& perltidy -g somefile.pl | |
225 | .Ve | |
226 | .PP | |
227 | Execute perltidy on file \fIsomefile.pl\fR and save a log file \fIsomefile.pl.LOG\fR | |
228 | which shows the nesting of braces, parentheses, and square brackets at | |
229 | the start of every line. | |
230 | .PP | |
231 | .Vb 1 | |
232 | \& perltidy -html somefile.pl | |
233 | .Ve | |
234 | .PP | |
235 | This will produce a file \fIsomefile.pl.html\fR containing the script with | |
236 | html markup. The output file will contain an embedded style sheet in | |
237 | the <\s-1HEAD\s0> section which may be edited to change the appearance. | |
238 | .PP | |
239 | .Vb 1 | |
240 | \& perltidy -html -css=mystyle.css somefile.pl | |
241 | .Ve | |
242 | .PP | |
243 | This will produce a file \fIsomefile.pl.html\fR containing the script with | |
244 | html markup. This output file will contain a link to a separate style | |
245 | sheet file \fImystyle.css\fR. If the file \fImystyle.css\fR does not exist, | |
246 | it will be created. If it exists, it will not be overwritten. | |
247 | .PP | |
248 | .Vb 1 | |
249 | \& perltidy -html -pre somefile.pl | |
250 | .Ve | |
251 | .PP | |
252 | Write an html snippet with only the \s-1PRE\s0 section to \fIsomefile.pl.html\fR. | |
253 | This is useful when code snippets are being formatted for inclusion in a | |
254 | larger web page. No style sheet will be written in this case. | |
255 | .PP | |
256 | .Vb 1 | |
257 | \& perltidy -html -ss >mystyle.css | |
258 | .Ve | |
259 | .PP | |
260 | Write a style sheet to \fImystyle.css\fR and exit. | |
261 | .PP | |
262 | .Vb 1 | |
263 | \& perltidy -html -frm mymodule.pm | |
264 | .Ve | |
265 | .PP | |
266 | Write html with a frame holding a table of contents and the source code. The | |
267 | output files will be \fImymodule.pm.html\fR (the frame), \fImymodule.pm.toc.html\fR | |
268 | (the table of contents), and \fImymodule.pm.src.html\fR (the source code). | |
269 | .SH "OPTIONS \- OVERVIEW" | |
270 | .IX Header "OPTIONS - OVERVIEW" | |
271 | The entire command line is scanned for options, and they are processed | |
272 | before any files are processed. As a result, it does not matter | |
273 | whether flags are before or after any filenames. However, the relative | |
274 | order of parameters is important, with later parameters overriding the | |
275 | values of earlier parameters. | |
276 | .PP | |
277 | For each parameter, there is a long name and a short name. The short | |
278 | names are convenient for keyboard input, while the long names are | |
279 | self-documenting and therefore useful in scripts. It is customary to | |
280 | use two leading dashes for long names, but one may be used. | |
281 | .PP | |
282 | Most parameters which serve as on/off flags can be negated with a | |
283 | leading \*(L"n\*(R" (for the short name) or a leading \*(L"no\*(R" or \*(L"no\-\*(R" (for the | |
284 | long name). For example, the flag to outdent long quotes is is \fB\-olq\fR | |
285 | or \fB\-\-outdent\-long\-quotes\fR. The flag to skip this is \fB\-nolq\fR | |
286 | or \fB\-\-nooutdent\-long\-quotes\fR or \fB\-\-no\-outdent\-long\-quotes\fR. | |
287 | .PP | |
288 | Options may not be bundled together. In other words, options \fB\-q\fR and | |
289 | \&\fB\-g\fR may \s-1NOT\s0 be entered as \fB\-qg\fR. | |
290 | .PP | |
291 | Option names may be terminated early as long as they are uniquely identified. | |
292 | For example, instead of \fB\-dump\-token\-types\fR, it would be sufficient to enter | |
293 | \&\fB\-dump\-tok\fR, or even \fB\-dump\-t\fR, to uniquely identify this command. | |
294 | .Sh "I/O control" | |
295 | .IX Subsection "I/O control" | |
296 | The following parameters concern the files which are read and written. | |
297 | .IP "\fB\-h\fR, \fB\-\-help\fR" 4 | |
298 | .IX Item "-h, --help" | |
299 | Show summary of usage and exit. | |
300 | .IP "\fB\-o\fR=filename, \fB\-\-outfile\fR=filename" 4 | |
301 | .IX Item "-o=filename, --outfile=filename" | |
302 | Name of the output file (only if a single input file is being | |
303 | processed). If no output file is specified, and output is not | |
304 | redirected to the standard output, the output will go to \fIfilename.tdy\fR. | |
305 | .IP "\fB\-st\fR, \fB\-\-standard\-output\fR" 4 | |
306 | .IX Item "-st, --standard-output" | |
307 | Perltidy must be able to operate on an arbitrarily large number of files | |
308 | in a single run, with each output being directed to a different output | |
309 | file. Obviously this would conflict with outputting to the single | |
310 | standard output device, so a special flag, \fB\-st\fR, is required to | |
311 | request outputting to the standard output. For example, | |
312 | .Sp | |
313 | .Vb 1 | |
314 | \& perltidy somefile.pl -st >somefile.new.pl | |
315 | .Ve | |
316 | .Sp | |
317 | This option may only be used if there is just a single input file. | |
318 | The default is \fB\-nst\fR or \fB\-nostandard\-output\fR. | |
319 | .IP "\fB\-se\fR, \fB\-\-standard\-error\-output\fR" 4 | |
320 | .IX Item "-se, --standard-error-output" | |
321 | If perltidy detects an error when processing file \fIsomefile.pl\fR, its | |
322 | default behavior is to write error messages to file \fIsomefile.pl.ERR\fR. | |
323 | Use \fB\-se\fR to cause all error messages to be sent to the standard error | |
324 | output stream instead. This directive may be negated with \fB\-nse\fR. | |
325 | Thus, you may place \fB\-se\fR in a \fI.perltidyrc\fR and override it when | |
326 | desired with \fB\-nse\fR on the command line. | |
327 | .IP "\fB\-oext\fR=ext, \fB\-\-output\-file\-extension\fR=ext" 4 | |
328 | .IX Item "-oext=ext, --output-file-extension=ext" | |
329 | Change the extension of the output file to be \fIext\fR instead of the | |
330 | default \fItdy\fR (or \fIhtml\fR in case the \-\fB\-html\fR option is used). | |
331 | See \*(L"Specifying File Extensions\*(R". | |
332 | .IP "\fB\-opath\fR=path, \fB\-\-output\-path\fR=path" 4 | |
333 | .IX Item "-opath=path, --output-path=path" | |
334 | When perltidy creates a filename for an output file, by default it merely | |
335 | appends an extension to the path and basename of the input file. This | |
336 | parameter causes the path to be changed to \fIpath\fR instead. | |
337 | .Sp | |
338 | The path should end in a valid path separator character, but perltidy will try | |
339 | to add one if it is missing. | |
340 | .Sp | |
341 | For example | |
342 | .Sp | |
343 | .Vb 1 | |
344 | \& perltidy somefile.pl -opath=/tmp/ | |
345 | .Ve | |
346 | .Sp | |
347 | will produce \fI/tmp/somefile.pl.tdy\fR. Otherwise, \fIsomefile.pl.tdy\fR will | |
348 | appear in whatever directory contains \fIsomefile.pl\fR. | |
349 | .Sp | |
350 | If the path contains spaces, it should be placed in quotes. | |
351 | .Sp | |
352 | This parameter will be ignored if output is being directed to standard output, | |
353 | or if it is being specified explicitly with the \fB\-o=s\fR parameter. | |
354 | .IP "\fB\-b\fR, \fB\-\-backup\-and\-modify\-in\-place\fR" 4 | |
355 | .IX Item "-b, --backup-and-modify-in-place" | |
356 | Modify the input file or files in-place and save the original with the | |
357 | extension \fI.bak\fR. Any existing \fI.bak\fR file will be deleted. See next item | |
358 | for changing the default backup extension. | |
359 | .Sp | |
360 | A \fB\-b\fR flag will be ignored if input is from standard input, or | |
361 | if the \fB\-html\fR flag is set. | |
362 | .IP "\fB\-bext\fR=ext, \fB\-\-backup\-file\-extension\fR=ext" 4 | |
363 | .IX Item "-bext=ext, --backup-file-extension=ext" | |
364 | Change the extension of the backup file to be something other than the | |
365 | default \fI.bak\fR. See \*(L"Specifying File Extensions\*(R". | |
366 | .IP "\fB\-w\fR, \fB\-\-warning\-output\fR" 4 | |
367 | .IX Item "-w, --warning-output" | |
368 | Setting \fB\-w\fR causes any non-critical warning | |
369 | messages to be reported as errors. These include messages | |
370 | about possible pod problems, possibly bad starting indentation level, | |
371 | and cautions about indirect object usage. The default, \fB\-nw\fR or | |
372 | \&\fB\-\-nowarning\-output\fR, is not to include these warnings. | |
373 | .IP "\fB\-q\fR, \fB\-\-quiet\fR" 4 | |
374 | .IX Item "-q, --quiet" | |
375 | Deactivate error messages and syntax checking (for running under | |
376 | an editor). | |
377 | .Sp | |
378 | For example, if you use a vi-style editor, such as vim, you may execute | |
379 | perltidy as a filter from within the editor using something like | |
380 | .Sp | |
381 | .Vb 1 | |
382 | \& :n1,n2!perltidy -q | |
383 | .Ve | |
384 | .Sp | |
385 | where \f(CW\*(C`n1,n2\*(C'\fR represents the selected text. Without the \fB\-q\fR flag, | |
386 | any error message may mess up your screen, so be prepared to use your | |
387 | \&\*(L"undo\*(R" key. | |
388 | .IP "\fB\-log\fR, \fB\-\-logfile\fR" 4 | |
389 | .IX Item "-log, --logfile" | |
390 | Save the \fI.LOG\fR file, which has many useful diagnostics. Perltidy always | |
391 | creates a \fI.LOG\fR file, but by default it is deleted unless a program bug is | |
392 | suspected. Setting the \fB\-log\fR flag forces the log file to be saved. | |
393 | .IP "\fB\-g=n\fR, \fB\-\-logfile\-gap=n\fR" 4 | |
394 | .IX Item "-g=n, --logfile-gap=n" | |
395 | Set maximum interval between input code lines in the logfile. This purpose of | |
396 | this flag is to assist in debugging nesting errors. The value of \f(CW\*(C`n\*(C'\fR is | |
397 | optional. If you set the flag \fB\-g\fR without the value of \f(CW\*(C`n\*(C'\fR, it will be | |
398 | taken to be 1, meaning that every line will be written to the log file. This | |
399 | can be helpful if you are looking for a brace, paren, or bracket nesting error. | |
400 | .Sp | |
401 | Setting \fB\-g\fR also causes the logfile to be saved, so it is not necessary to | |
402 | also include \fB\-log\fR. | |
403 | .Sp | |
404 | If no \fB\-g\fR flag is given, a value of 50 will be used, meaning that at least | |
405 | every 50th line will be recorded in the logfile. This helps prevent | |
406 | excessively long log files. | |
407 | .Sp | |
408 | Setting a negative value of \f(CW\*(C`n\*(C'\fR is the same as not setting \fB\-g\fR at all. | |
409 | .IP "\fB\-npro\fR \fB\-\-noprofile\fR" 4 | |
410 | .IX Item "-npro --noprofile" | |
411 | Ignore any \fI.perltidyrc\fR command file. Normally, perltidy looks first in | |
412 | your current directory for a \fI.perltidyrc\fR file of parameters. (The format | |
413 | is described below). If it finds one, it applies those options to the | |
414 | initial default values, and then it applies any that have been defined | |
415 | on the command line. If no \fI.perltidyrc\fR file is found, it looks for one | |
416 | in your home directory. | |
417 | .Sp | |
418 | If you set the \fB\-npro\fR flag, perltidy will not look for this file. | |
419 | .IP "\fB\-pro=filename\fR or \fB\-\-profile=filename\fR" 4 | |
420 | .IX Item "-pro=filename or --profile=filename" | |
421 | To simplify testing and switching .perltidyrc files, this command may be | |
422 | used to specify a configuration file which will override the default | |
423 | name of .perltidyrc. There must not be a space on either side of the | |
424 | \&'=' sign. For example, the line | |
425 | .Sp | |
426 | .Vb 1 | |
427 | \& perltidy -pro=testcfg | |
428 | .Ve | |
429 | .Sp | |
430 | would cause file \fItestcfg\fR to be used instead of the | |
431 | default \fI.perltidyrc\fR. | |
432 | .IP "\fB\-opt\fR, \fB\-\-show\-options\fR" 4 | |
433 | .IX Item "-opt, --show-options" | |
434 | Write a list of all options used to the \fI.LOG\fR file. | |
435 | Please see \fB\-\-dump\-options\fR for a simpler way to do this. | |
436 | .IP "\fB\-f\fR, \fB\-\-force\-read\-binary\fR" 4 | |
437 | .IX Item "-f, --force-read-binary" | |
438 | Force perltidy to process binary files. To avoid producing excessive | |
439 | error messages, perltidy skips files identified by the system as non\-text. | |
440 | However, valid perl scripts containing binary data may sometimes be identified | |
441 | as non\-text, and this flag forces perltidy to process them. | |
442 | .SH "FORMATTING OPTIONS" | |
443 | .IX Header "FORMATTING OPTIONS" | |
444 | .Sh "Basic Options" | |
445 | .IX Subsection "Basic Options" | |
446 | .IP "\fB\-l=n\fR, \fB\-\-maximum\-line\-length=n\fR" 4 | |
447 | .IX Item "-l=n, --maximum-line-length=n" | |
448 | The default maximum line length is n=80 characters. Perltidy will try | |
449 | to find line break points to keep lines below this length. However, long | |
450 | quotes and side comments may cause lines to exceed this length. | |
451 | Setting \fB\-l=0\fR is equivalent to setting \fB\-l=(a large number)\fR. | |
452 | .IP "\fB\-i=n\fR, \fB\-\-indent\-columns=n\fR" 4 | |
453 | .IX Item "-i=n, --indent-columns=n" | |
454 | Use n columns per indentation level (default n=4). | |
455 | .IP "tabs" 4 | |
456 | .IX Item "tabs" | |
457 | Using tab characters will almost certainly lead to future portability | |
458 | and maintenance problems, so the default and recommendation is not to | |
459 | use them. For those who prefer tabs, however, there are two different | |
460 | options. | |
461 | .Sp | |
462 | Except for possibly introducing tab indentation characters, as outlined | |
463 | below, perltidy does not introduce any tab characters into your file, | |
464 | and it removes any tabs from the code (unless requested not to do so | |
465 | with \fB\-fws\fR). If you have any tabs in your comments, quotes, or | |
466 | here\-documents, they will remain. | |
467 | .RS 4 | |
468 | .IP "\fB\-et=n\fR, \fB\-\-entab\-leading\-whitespace\fR" 4 | |
469 | .IX Item "-et=n, --entab-leading-whitespace" | |
470 | This flag causes each \fBn\fR initial space characters to be replaced by | |
471 | one tab character. Note that the integer \fBn\fR is completely independent | |
472 | of the integer specified for indentation parameter, \fB\-i=n\fR. | |
473 | .IP "\fB\-t\fR, \fB\-\-tabs\fR" 4 | |
474 | .IX Item "-t, --tabs" | |
475 | This flag causes one leading tab character to be inserted for each level | |
476 | of indentation. Certain other features are incompatible with this | |
477 | option, and if these options are also given, then a warning message will | |
478 | be issued and this flag will be unset. One example is the \fB\-lp\fR | |
479 | option. | |
480 | .RE | |
481 | .RS 4 | |
482 | .RE | |
483 | .IP "\fB\-syn\fR, \fB\-\-check\-syntax\fR" 4 | |
484 | .IX Item "-syn, --check-syntax" | |
485 | This flag causes perltidy to run \f(CW\*(C`perl \-c \-T\*(C'\fR to check syntax of input | |
486 | and output. (To change the flags passed to perl, see the next | |
487 | item, \fB\-pscf\fR). The results are written to the \fI.LOG\fR file, which | |
488 | will be saved if an error is detected in the output script. The output | |
489 | script is not checked if the input script has a syntax error. Perltidy | |
490 | does its own checking, but this option employs perl to get a \*(L"second | |
491 | opinion\*(R". | |
492 | .Sp | |
493 | If perl reports errors in the input file, they will not be reported in | |
494 | the error output unless the \fB\-warning\-output\fR flag is given. | |
495 | .Sp | |
496 | The default is \fBnot\fR to do this type of syntax checking (although | |
497 | perltidy will still do as much self-checking as possible). The reason | |
498 | is that it causes all code in \s-1BEGIN\s0 blocks to be executed, for all | |
499 | modules being used, and this opens the door to security issues and | |
500 | infinite loops when running perltidy. | |
501 | .IP "\fB\-pscf=s\fR, \fB\-perl\-syntax\-check\-flags=s\fR" 4 | |
502 | .IX Item "-pscf=s, -perl-syntax-check-flags=s" | |
503 | When perl is invoked to check syntax, the normal flags are \f(CW\*(C`\-c \-T\*(C'\fR. In | |
504 | addition, if the \fB\-x\fR flag is given to perltidy, then perl will also be | |
505 | passed a \fB\-x\fR flag. It should not normally be necessary to change | |
506 | these flags, but it can be done with the \fB\-pscf=s\fR flag. For example, | |
507 | if the taint flag, \f(CW\*(C`\-T\*(C'\fR, is not wanted, the flag could be set to be just | |
508 | \&\fB\-pscf=\-c\fR. | |
509 | .Sp | |
510 | Perltidy will pass your string to perl with the exception that it will | |
511 | add a \fB\-c\fR and \fB\-x\fR if appropriate. The \fI.LOG\fR file will show | |
512 | exactly what flags were passed to perl. | |
513 | .IP "\fB\-io\fR, \fB\-\-indent\-only\fR" 4 | |
514 | .IX Item "-io, --indent-only" | |
515 | This flag is used to deactivate all formatting and line break changes. | |
516 | When it is in effect, the only change to the script will be indentation. | |
517 | And any flags controlling whitespace and newlines will be ignored. You | |
518 | might want to use this if you are perfectly happy with your whitespace | |
519 | and line breaks, and merely want perltidy to handle the indentation. | |
520 | (This also speeds up perltidy by well over a factor of two, so it might be | |
521 | useful when perltidy is merely being used to help find a brace error in | |
522 | a large script). | |
523 | .Sp | |
524 | Setting this flag is equivalent to setting \fB\-\-freeze\-newlines\fR and | |
525 | \&\fB\-\-freeze\-whitespace\fR. | |
526 | .IP "\fB\-ole=s\fR, \fB\-\-output\-line\-ending=s\fR" 4 | |
527 | .IX Item "-ole=s, --output-line-ending=s" | |
528 | where s=\f(CW\*(C`win\*(C'\fR, \f(CW\*(C`dos\*(C'\fR, \f(CW\*(C`unix\*(C'\fR, or \f(CW\*(C`mac\*(C'\fR. This flag tells perltidy | |
529 | to output line endings for a specific system. Normally, | |
530 | perltidy writes files with the line separator character of the host | |
531 | system. The \f(CW\*(C`win\*(C'\fR and \f(CW\*(C`dos\*(C'\fR flags have an identical result. | |
532 | \&\fB\s-1NOTE\s0\fR: This only works under unix-like systems and is ignored under | |
533 | other systems. | |
534 | .IP "\fB\-ple\fR, \fB\-\-preserve\-line\-endings\fR" 4 | |
535 | .IX Item "-ple, --preserve-line-endings" | |
536 | This flag tells perltidy to write its output files with the same line | |
537 | endings as the input file, if possible. It should work for | |
538 | \&\fBdos\fR, \fBunix\fR, and \fBmac\fR line endings. It will only work if perltidy | |
539 | input comes from a filename (rather than stdin, for example). If | |
540 | perltidy has trouble determining the input file line ending, it will | |
541 | revert to the default behavior of using the line ending of the host system. | |
542 | \&\fB\s-1NOTE\s0\fR: This only works under unix-like systems and is ignored under | |
543 | other systems. | |
544 | .Sh "Code Indentation Control" | |
545 | .IX Subsection "Code Indentation Control" | |
546 | .IP "\fB\-ci=n\fR, \fB\-\-continuation\-indentation=n\fR" 4 | |
547 | .IX Item "-ci=n, --continuation-indentation=n" | |
548 | Continuation indentation is extra indentation spaces applied when | |
549 | a long line is broken. The default is n=2, illustrated here: | |
550 | .Sp | |
551 | .Vb 2 | |
552 | \& my $level = # -ci=2 | |
553 | \& ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level; | |
554 | .Ve | |
555 | .Sp | |
556 | The same example, with n=0, is a little harder to read: | |
557 | .Sp | |
558 | .Vb 2 | |
559 | \& my $level = # -ci=0 | |
560 | \& ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level; | |
561 | .Ve | |
562 | .Sp | |
563 | The value given to \fB\-ci\fR is also used by some commands when a small | |
564 | space is required. Examples are commands for outdenting labels, | |
565 | \&\fB\-ola\fR, and control keywords, \fB\-okw\fR. | |
566 | .Sp | |
567 | When default values are not used, it is suggested that the value \fBn\fR | |
568 | given with \fB\-ci=n\fR be no more than about one-half of the number of | |
569 | spaces assigned to a full indentation level on the \fB\-i=n\fR command. | |
570 | .IP "\fB\-sil=n\fR \fB\-\-starting\-indentation\-level=n\fR" 4 | |
571 | .IX Item "-sil=n --starting-indentation-level=n" | |
572 | By default, perltidy examines the input file and tries to determine the | |
573 | starting indentation level. While it is often zero, it may not be | |
574 | zero for a code snippet being sent from an editing session. If the | |
575 | default method does not work correctly, or you want to change the | |
576 | starting level, use \fB\-sil=n\fR, to force the starting level to be n. | |
577 | .IP "List indentation using \fB\-lp\fR, \fB\-\-line\-up\-parentheses\fR" 4 | |
578 | .IX Item "List indentation using -lp, --line-up-parentheses" | |
579 | By default, perltidy indents lists with 4 spaces, or whatever value | |
580 | is specified with \fB\-i=n\fR. Here is a small list formatted in this way: | |
581 | .Sp | |
582 | .Vb 5 | |
583 | \& # perltidy (default) | |
584 | \& @month_of_year = ( | |
585 | \& 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', | |
586 | \& 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' | |
587 | \& ); | |
588 | .Ve | |
589 | .Sp | |
590 | Use the \fB\-lp\fR flag to add extra indentation to cause the data to begin | |
591 | past the opening parentheses of a sub call or list, or opening square | |
592 | bracket of an anonymous array, or opening curly brace of an anonymous | |
593 | hash. With this option, the above list would become: | |
594 | .Sp | |
595 | .Vb 5 | |
596 | \& # perltidy -lp | |
597 | \& @month_of_year = ( | |
598 | \& 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', | |
599 | \& 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' | |
600 | \& ); | |
601 | .Ve | |
602 | .Sp | |
603 | If the available line length (see \fB\-l=n\fR ) does not permit this much | |
604 | space, perltidy will use less. For alternate placement of the | |
605 | closing paren, see the next section. | |
606 | .Sp | |
607 | This option has no effect on code \s-1BLOCKS\s0, such as if/then/else blocks, | |
608 | which always use whatever is specified with \fB\-i=n\fR. Also, the | |
609 | existence of line breaks and/or block comments between the opening and | |
610 | closing parens may cause perltidy to temporarily revert to its default | |
611 | method. | |
612 | .Sp | |
613 | Note: The \fB\-lp\fR option may not be used together with the \fB\-t\fR tabs option. | |
614 | It may, however, be used with the \fB\-et=n\fR tab method. | |
615 | .Sp | |
616 | In addition, any parameter which significantly restricts the ability of | |
617 | perltidy to choose newlines will conflict with \fB\-lp\fR and will cause | |
618 | \&\fB\-lp\fR to be deactivated. These include \fB\-io\fR, \fB\-fnl\fR, \fB\-nanl\fR, and | |
619 | \&\fB\-ndnl\fR. The reason is that the \fB\-lp\fR indentation style can require | |
620 | the careful coordination of an arbitrary number of break points in | |
621 | hierarchical lists, and these flags may prevent that. | |
622 | .IP "\fB\-cti=n\fR, \fB\-\-closing\-token\-indentation\fR" 4 | |
623 | .IX Item "-cti=n, --closing-token-indentation" | |
624 | The \fB\-cti=n\fR flag controls the indentation of a line beginning with | |
625 | a \f(CW\*(C`)\*(C'\fR, \f(CW\*(C`]\*(C'\fR, or a non-block \f(CW\*(C`}\*(C'\fR. Such a line receives: | |
626 | .Sp | |
627 | .Vb 5 | |
628 | \& -cti = 0 no extra indentation (default) | |
629 | \& -cti = 1 extra indentation such that the closing token | |
630 | \& aligns with its opening token. | |
631 | \& -cti = 2 one extra indentation level if the line looks like: | |
632 | \& ); or ]; or }; | |
633 | .Ve | |
634 | .Sp | |
635 | The flags \fB\-cti=1\fR and \fB\-cti=2\fR work well with the \fB\-lp\fR flag (previous | |
636 | section). | |
637 | .Sp | |
638 | .Vb 5 | |
639 | \& # perltidy -lp -cti=1 | |
640 | \& @month_of_year = ( | |
641 | \& 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', | |
642 | \& 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' | |
643 | \& ); | |
644 | .Ve | |
645 | .Sp | |
646 | .Vb 5 | |
647 | \& # perltidy -lp -cti=2 | |
648 | \& @month_of_year = ( | |
649 | \& 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', | |
650 | \& 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' | |
651 | \& ); | |
652 | .Ve | |
653 | .Sp | |
654 | These flags are merely hints to the formatter and they may not always be | |
655 | followed. In particular, if \-lp is not being used, the indentation for | |
656 | \&\fBcti=1\fR is constrained to be no more than one indentation level. | |
657 | .Sp | |
658 | If desired, this control can be applied independently to each of the | |
659 | closing container token types. In fact, \fB\-cti=n\fR is merely an | |
660 | abbreviation for \fB\-cpi=n \-csbi=n \-cbi=n\fR, where: | |
661 | \&\fB\-cpi\fR or \fB\-closing\-paren\-indentation\fR controls \fB)\fR's, | |
662 | \&\fB\-csbi\fR or \fB\-closing\-square\-bracket\-indentation\fR controls \fB]\fR's, | |
663 | \&\fB\-cbi\fR or \fB\-closing\-brace\-indentation\fR controls non-block \fB}\fR's. | |
664 | .IP "\fB\-icp\fR, \fB\-\-indent\-closing\-paren\fR" 4 | |
665 | .IX Item "-icp, --indent-closing-paren" | |
666 | The \fB\-icp\fR flag is equivalent to | |
667 | \&\fB\-cti=2\fR, described in the previous section. The \fB\-nicp\fR flag is | |
668 | equivalent \fB\-cti=0\fR. They are included for backwards compatability. | |
669 | .IP "\fB\-icb\fR, \fB\-\-indent\-closing\-brace\fR" 4 | |
670 | .IX Item "-icb, --indent-closing-brace" | |
671 | The \fB\-icb\fR option leaves a brace which terminates a code block | |
672 | indented with the same indentation as the previous line. For example, | |
673 | .Sp | |
674 | .Vb 6 | |
675 | \& if ($task) { | |
676 | \& yyy(); | |
677 | \& } # -icb | |
678 | \& else { | |
679 | \& zzz(); | |
680 | \& } | |
681 | .Ve | |
682 | .Sp | |
683 | The default is not to do this, indicated by \fB\-nicb\fR. | |
684 | .IP "\fB\-olq\fR, \fB\-\-outdent\-long\-quotes\fR" 4 | |
685 | .IX Item "-olq, --outdent-long-quotes" | |
686 | When \fB\-olq\fR is set, lines which is a quoted string longer than the | |
687 | value \fBmaximum-line-length\fR will have their indentation removed to make | |
688 | them more readable. This is the default. To prevent such out\-denting, | |
689 | use \fB\-nolq\fR or \fB\-\-nooutdent\-long\-lines\fR. | |
690 | .IP "\fB\-oll\fR, \fB\-\-outdent\-long\-lines\fR" 4 | |
691 | .IX Item "-oll, --outdent-long-lines" | |
692 | This command is equivalent to \fB\-\-outdent\-long\-quotes\fR and | |
693 | \&\fB\-\-outdent\-long\-comments\fR, and it is included for compatibility with previous | |
694 | versions of perltidy. The negation of this also works, \fB\-noll\fR or | |
695 | \&\fB\-\-nooutdent\-long\-lines\fR, and is equivalent to setting \fB\-nolq\fR and \fB\-nolc\fR. | |
696 | .IP "Outdenting Labels: \fB\-ola\fR, \fB\-\-outdent\-labels\fR" 4 | |
697 | .IX Item "Outdenting Labels: -ola, --outdent-labels" | |
698 | This command will cause labels to be outdented by 2 spaces (or whatever \fB\-ci\fR | |
699 | has been set to), if possible. This is the default. For example: | |
700 | .Sp | |
701 | .Vb 6 | |
702 | \& my $i; | |
703 | \& LOOP: while ( $i = <FOTOS> ) { | |
704 | \& chomp($i); | |
705 | \& next unless $i; | |
706 | \& fixit($i); | |
707 | \& } | |
708 | .Ve | |
709 | .Sp | |
710 | Use \fB\-nola\fR to not outdent labels. | |
711 | .IP "Outdenting Keywords" 4 | |
712 | .IX Item "Outdenting Keywords" | |
713 | .RS 4 | |
714 | .PD 0 | |
715 | .IP "\fB\-okw\fR, \fB\-\-outdent\-keywords\fR" 4 | |
716 | .IX Item "-okw, --outdent-keywords" | |
717 | .PD | |
718 | The command \fB\-okw\fR will will cause certain leading control keywords to | |
719 | be outdented by 2 spaces (or whatever \fB\-ci\fR has been set to), if | |
720 | possible. By default, these keywords are \f(CW\*(C`redo\*(C'\fR, \f(CW\*(C`next\*(C'\fR, \f(CW\*(C`last\*(C'\fR, | |
721 | \&\f(CW\*(C`goto\*(C'\fR, and \f(CW\*(C`return\*(C'\fR. The intention is to make these control keywords | |
722 | easier to see. To change this list of keywords being outdented, see | |
723 | the next section. | |
724 | .Sp | |
725 | For example, using \f(CW\*(C`perltidy \-okw\*(C'\fR on the previous example gives: | |
726 | .Sp | |
727 | .Vb 6 | |
728 | \& my $i; | |
729 | \& LOOP: while ( $i = <FOTOS> ) { | |
730 | \& chomp($i); | |
731 | \& next unless $i; | |
732 | \& fixit($i); | |
733 | \& } | |
734 | .Ve | |
735 | .Sp | |
736 | The default is not to do this. | |
737 | .IP "Specifying Outdented Keywords: \fB\-okwl=string\fR, \fB\-\-outdent\-keyword\-list=string\fR" 4 | |
738 | .IX Item "Specifying Outdented Keywords: -okwl=string, --outdent-keyword-list=string" | |
739 | This command can be used to change the keywords which are outdented with | |
740 | the \fB\-okw\fR command. The parameter \fBstring\fR is a required list of perl | |
741 | keywords, which should be placed in quotes if there are more than one. | |
742 | By itself, it does not cause any outdenting to occur, so the \fB\-okw\fR | |
743 | command is still required. | |
744 | .Sp | |
745 | For example, the commands \f(CW\*(C`\-okwl="next last redo goto" \-okw\*(C'\fR will cause | |
746 | those four keywords to be outdented. It is probably simplest to place | |
747 | any \fB\-okwl\fR command in a \fI.perltidyrc\fR file. | |
748 | .RE | |
749 | .RS 4 | |
750 | .RE | |
751 | .Sh "Whitespace Control" | |
752 | .IX Subsection "Whitespace Control" | |
753 | Whitespace refers to the blank space between variables, operators, | |
754 | and other code tokens. | |
755 | .IP "\fB\-fws\fR, \fB\-\-freeze\-whitespace\fR" 4 | |
756 | .IX Item "-fws, --freeze-whitespace" | |
757 | This flag causes your original whitespace to remain unchanged, and | |
758 | causes the rest of the whitespace commands in this section, the | |
759 | Code Indentation section, and | |
760 | the Comment Control section to be ignored. | |
761 | .IP "Tightness of curly braces, parentheses, and square brackets." 4 | |
762 | .IX Item "Tightness of curly braces, parentheses, and square brackets." | |
763 | Here the term \*(L"tightness\*(R" will mean the closeness with which | |
764 | pairs of enclosing tokens, such as parentheses, contain the quantities | |
765 | within. A numerical value of 0, 1, or 2 defines the tightness, with | |
766 | 0 being least tight and 2 being most tight. Spaces within containers | |
767 | are always symmetric, so if there is a space after a \f(CW\*(C`(\*(C'\fR then there | |
768 | will be a space before the corresponding \f(CW\*(C`)\*(C'\fR. | |
769 | .Sp | |
770 | The \fB\-pt=n\fR or \fB\-\-paren\-tightness=n\fR parameter controls the space within | |
771 | parens. The example below shows the effect of the three possible | |
772 | values, 0, 1, and 2: | |
773 | .Sp | |
774 | .Vb 3 | |
775 | \& if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0 | |
776 | \& if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default) | |
777 | \& if ((my $len_tab = length($tabstr)) > 0) { # -pt=2 | |
778 | .Ve | |
779 | .Sp | |
780 | When n is 0, there is always a space to the right of a '(' and to the left | |
781 | of a ')'. For n=2 there is never a space. For n=1, the default, there | |
782 | is a space unless the quantity within the parens is a single token, such | |
783 | as an identifier or quoted string. | |
784 | .Sp | |
785 | Likewise, the parameter \fB\-sbt=n\fR or \fB\-\-square\-bracket\-tightness=n\fR | |
786 | controls the space within square brackets, as illustrated below. | |
787 | .Sp | |
788 | .Vb 3 | |
789 | \& $width = $col[ $j + $k ] - $col[ $j ]; # -sbt=0 | |
790 | \& $width = $col[ $j + $k ] - $col[$j]; # -sbt=1 (default) | |
791 | \& $width = $col[$j + $k] - $col[$j]; # -sbt=2 | |
792 | .Ve | |
793 | .Sp | |
794 | Curly braces which do not contain code blocks are controlled by | |
795 | the parameter \fB\-bt=n\fR or \fB\-\-brace\-tightness=n\fR. | |
796 | .Sp | |
797 | .Vb 3 | |
798 | \& $obj->{ $parsed_sql->{ 'table' }[0] }; # -bt=0 | |
799 | \& $obj->{ $parsed_sql->{'table'}[0] }; # -bt=1 (default) | |
800 | \& $obj->{$parsed_sql->{'table'}[0]}; # -bt=2 | |
801 | .Ve | |
802 | .Sp | |
803 | And finally, curly braces which contain blocks of code are controlled by the | |
804 | parameter \fB\-bbt=n\fR or \fB\-\-block\-brace\-tightness=n\fR as illustrated in the | |
805 | example below. | |
806 | .Sp | |
807 | .Vb 3 | |
808 | \& %bf = map { $_ => -M $_ } grep { /\e.deb$/ } dirents '.'; # -bbt=0 (default) | |
809 | \& %bf = map { $_ => -M $_ } grep {/\e.deb$/} dirents '.'; # -bbt=1 | |
810 | \& %bf = map {$_ => -M $_} grep {/\e.deb$/} dirents '.'; # -bbt=2 | |
811 | .Ve | |
812 | .IP "\fB\-sts\fR, \fB\-\-space\-terminal\-semicolon\fR" 4 | |
813 | .IX Item "-sts, --space-terminal-semicolon" | |
814 | Some programmers prefer a space before all terminal semicolons. The | |
815 | default is for no such space, and is indicated with \fB\-nsts\fR or | |
816 | \&\fB\-\-nospace\-terminal\-semicolon\fR. | |
817 | .Sp | |
818 | .Vb 2 | |
819 | \& $i = 1 ; # -sts | |
820 | \& $i = 1; # -nsts (default) | |
821 | .Ve | |
822 | .IP "\fB\-sfs\fR, \fB\-\-space\-for\-semicolon\fR" 4 | |
823 | .IX Item "-sfs, --space-for-semicolon" | |
824 | Semicolons within \fBfor\fR loops may sometimes be hard to see, | |
825 | particularly when commas are also present. This option places spaces on | |
826 | both sides of these special semicolons, and is the default. Use | |
827 | \&\fB\-nsfs\fR or \fB\-\-nospace\-for\-semicolon\fR to deactivate it. | |
828 | .Sp | |
829 | .Vb 2 | |
830 | \& for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default) | |
831 | \& for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs | |
832 | .Ve | |
833 | .IP "\fB\-asc\fR, \fB\-\-add\-semicolons\fR" 4 | |
834 | .IX Item "-asc, --add-semicolons" | |
835 | Setting \fB\-asc\fR allows perltidy to add any missing optional semicolon at the end | |
836 | of a line which is followed by a closing curly brace on the next line. This | |
837 | is the default, and may be deactivated with \fB\-nasc\fR or \fB\-\-noadd\-semicolons\fR. | |
838 | .IP "\fB\-dsm\fR, \fB\-\-delete\-semicolons\fR" 4 | |
839 | .IX Item "-dsm, --delete-semicolons" | |
840 | Setting \fB\-dsm\fR allows perltidy to delete extra semicolons which are | |
841 | simply empty statements. This is the default, and may be deactivated | |
842 | with \fB\-ndsm\fR or \fB\-\-nodelete\-semicolons\fR. (Such semicolons are not | |
843 | deleted, however, if they would promote a side comment to a block | |
844 | comment). | |
845 | .IP "\fB\-aws\fR, \fB\-\-add\-whitespace\fR" 4 | |
846 | .IX Item "-aws, --add-whitespace" | |
847 | Setting this option allows perltidy to add certain whitespace improve | |
848 | code readability. This is the default. If you do not want any | |
849 | whitespace added, but are willing to have some whitespace deleted, use | |
850 | \&\fB\-naws\fR. (Use \fB\-fws\fR to leave whitespace completely unchanged). | |
851 | .IP "\fB\-dws\fR, \fB\-\-delete\-old\-whitespace\fR" 4 | |
852 | .IX Item "-dws, --delete-old-whitespace" | |
853 | Setting this option allows perltidy to remove some old whitespace | |
854 | between characters, if necessary. This is the default. If you | |
855 | do not want any old whitespace removed, use \fB\-ndws\fR or | |
856 | \&\fB\-\-nodelete\-old\-whitespace\fR. | |
857 | .IP "Detailed whitespace controls around tokens" 4 | |
858 | .IX Item "Detailed whitespace controls around tokens" | |
859 | For those who want more detailed control over the whitespace around | |
860 | tokens, there are four parameters which can directly modify the default | |
861 | whitespace rules built into perltidy for any token. They are: | |
862 | .Sp | |
863 | \&\fB\-wls=s\fR or \fB\-\-want\-left\-space=s\fR, | |
864 | .Sp | |
865 | \&\fB\-nwls=s\fR or \fB\-\-nowant\-left\-space=s\fR, | |
866 | .Sp | |
867 | \&\fB\-wrs=s\fR or \fB\-\-want\-right\-space=s\fR, | |
868 | .Sp | |
869 | \&\fB\-nwrs=s\fR or \fB\-\-nowant\-right\-space=s\fR. | |
870 | .Sp | |
871 | These parameters are each followed by a quoted string, \fBs\fR, containing a | |
872 | list of token types. No more than one of each of these parameters | |
873 | should be specified, because repeating a command-line parameter | |
874 | always overwrites the previous one before perltidy ever sees it. | |
875 | .Sp | |
876 | To illustrate how these are used, suppose it is desired that there be no | |
877 | space on either side of the token types \fB= + \- / *\fR. The following two | |
878 | parameters would specify this desire: | |
879 | .Sp | |
880 | .Vb 1 | |
881 | \& -nwls="= + - / *" -nwrs="= + - / *" | |
882 | .Ve | |
883 | .Sp | |
884 | (Note that the token types are in quotes, and that they are separated by | |
885 | spaces). With these modified whitespace rules, the following line of math: | |
886 | .Sp | |
887 | .Vb 1 | |
888 | \& $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a ); | |
889 | .Ve | |
890 | .Sp | |
891 | becomes this: | |
892 | .Sp | |
893 | .Vb 1 | |
894 | \& $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a ); | |
895 | .Ve | |
896 | .Sp | |
897 | These parameters should be considered to be hints to perltidy rather | |
898 | than fixed rules, because perltidy must try to resolve conflicts that | |
899 | arise between them and all of the other rules that it uses. One | |
900 | conflict that can arise is if, between two tokens, the left token wants | |
901 | a space and the right one doesn't. In this case, the token not wanting | |
902 | a space takes priority. | |
903 | .Sp | |
904 | It is necessary to have a list of all token types in order to create | |
905 | this type of input. Such a list can be obtained by the command | |
906 | \&\fB\-dump\-token\-types\fR. | |
907 | .IP "Space between keyword and opening paren" 4 | |
908 | .IX Item "Space between keyword and opening paren" | |
909 | When an opening paren follows a keyword, no space is introduced after the | |
910 | keyword, unless it is (by default) one of these: | |
911 | .Sp | |
912 | .Vb 2 | |
913 | \& my local our and or eq ne if else elsif until unless | |
914 | \& while for foreach return switch case given when | |
915 | .Ve | |
916 | .Sp | |
917 | These defaults can be modified with two commands: | |
918 | .Sp | |
919 | \&\fB\-sak=s\fR or \fB\-\-space\-after\-keyword=s\fR adds keywords. | |
920 | .Sp | |
921 | \&\fB\-nsak=s\fR or \fB\-\-nospace\-after\-keyword=s\fR removes keywords. | |
922 | .Sp | |
923 | where \fBs\fR is a list of keywords (in quotes if necessary). For example, | |
924 | .Sp | |
925 | .Vb 2 | |
926 | \& my ( $a, $b, $c ) = @_; # default | |
927 | \& my( $a, $b, $c ) = @_; # -nsak="my local our" | |
928 | .Ve | |
929 | .ie n .IP "Trimming whitespace around ""qw"" quotes" 4 | |
930 | .el .IP "Trimming whitespace around \f(CWqw\fR quotes" 4 | |
931 | .IX Item "Trimming whitespace around qw quotes" | |
932 | \&\fB\-tqw\fR or \fB\-\-trim\-qw\fR provide the default behavior of trimming | |
933 | spaces around multi-line \f(CW\*(C`qw\*(C'\fR quotes and indenting them appropriately. | |
934 | .Sp | |
935 | \&\fB\-ntqw\fR or \fB\-\-notrim\-qw\fR cause leading and trailing whitespace around | |
936 | multi-line \f(CW\*(C`qw\*(C'\fR quotes to be left unchanged. This option will not | |
937 | normally be necessary, but was added for testing purposes, because in | |
938 | some versions of perl, trimming \f(CW\*(C`qw\*(C'\fR quotes changes the syntax tree. | |
939 | .Sh "Comment Controls" | |
940 | .IX Subsection "Comment Controls" | |
941 | Perltidy has a number of ways to control the appearance of both block comments | |
942 | and side comments. The term \fBblock comment\fR here refers to a full-line | |
943 | comment, whereas \fBside comment\fR will refer to a comment which appears on a | |
944 | line to the right of some code. | |
945 | .IP "\fB\-ibc\fR, \fB\-\-indent\-block\-comments\fR" 4 | |
946 | .IX Item "-ibc, --indent-block-comments" | |
947 | Block comments normally look best when they are indented to the same | |
948 | level as the code which follows them. This is the default behavior, but | |
949 | you may use \fB\-nibc\fR to keep block comments left\-justified. Here is an | |
950 | example: | |
951 | .Sp | |
952 | .Vb 2 | |
953 | \& # this comment is indented (-ibc, default) | |
954 | \& if ($task) { yyy(); } | |
955 | .Ve | |
956 | .Sp | |
957 | The alternative is \fB\-nibc\fR: | |
958 | .Sp | |
959 | .Vb 2 | |
960 | \& # this comment is not indented (-nibc) | |
961 | \& if ($task) { yyy(); } | |
962 | .Ve | |
963 | .Sp | |
964 | See also the next item, \fB\-isbc\fR, as well as \fB\-sbc\fR, for other ways to | |
965 | have some indented and some outdented block comments. | |
966 | .IP "\fB\-isbc\fR, \fB\-\-indent\-spaced\-block\-comments\fR" 4 | |
967 | .IX Item "-isbc, --indent-spaced-block-comments" | |
968 | If there is no leading space on the line, then the comment will not be | |
969 | indented, and otherwise it may be. | |
970 | .Sp | |
971 | If both \fB\-ibc\fR and \fB\-isbc\fR are set, then \fB\-isbc\fR takes priority. | |
972 | .IP "\fB\-olc\fR, \fB\-\-outdent\-long\-comments\fR" 4 | |
973 | .IX Item "-olc, --outdent-long-comments" | |
974 | When \fB\-olc\fR is set, lines which are full-line (block) comments longer | |
975 | than the value \fBmaximum-line-length\fR will have their indentation | |
976 | removed. The default is not to do this. | |
977 | .IP "\fB\-msc=n\fR, \fB\-\-minimum\-space\-to\-comment=n\fR" 4 | |
978 | .IX Item "-msc=n, --minimum-space-to-comment=n" | |
979 | Side comments look best when lined up several spaces to the right of | |
980 | code. Perltidy will try to keep comments at least n spaces to the | |
981 | right. The default is n=4 spaces. | |
982 | .IP "\fB\-hsc\fR, \fB\-\-hanging\-side\-comments\fR" 4 | |
983 | .IX Item "-hsc, --hanging-side-comments" | |
984 | By default, perltidy tries to identify and align \*(L"hanging side | |
985 | comments\*(R", which are something like this: | |
986 | .Sp | |
987 | .Vb 3 | |
988 | \& my $IGNORE = 0; # This is a side comment | |
989 | \& # This is a hanging side comment | |
990 | \& # And so is this | |
991 | .Ve | |
992 | .Sp | |
993 | A comment is considered to be a hanging side comment if (1) it immediately | |
994 | follows a line with a side comment, or another hanging side comment, and | |
995 | (2) there is some leading whitespace on the line. | |
996 | To deactivate this feature, use \fB\-nhsc\fR or \fB\-\-nohanging\-side\-comments\fR. | |
997 | If block comments are preceded by a blank line, or have no leading | |
998 | whitespace, they will not be mistaken as hanging side comments. | |
999 | .IP "Closing Side Comments" 4 | |
1000 | .IX Item "Closing Side Comments" | |
1001 | A closing side comment is a special comment which perltidy can | |
1002 | automatically create and place after the closing brace of a code block. | |
1003 | They can be useful for code maintenance and debugging. The command | |
1004 | \&\fB\-csc\fR (or \fB\-closing\-side\-comments\fR) adds or updates closing side | |
1005 | comments. For example, here is a small code snippet | |
1006 | .Sp | |
1007 | .Vb 8 | |
1008 | \& sub message { | |
1009 | \& if ( !defined( $_[0] ) ) { | |
1010 | \& print("Hello, World\en"); | |
1011 | \& } | |
1012 | \& else { | |
1013 | \& print( $_[0], "\en" ); | |
1014 | \& } | |
1015 | \& } | |
1016 | .Ve | |
1017 | .Sp | |
1018 | And here is the result of processing with \f(CW\*(C`perltidy \-csc\*(C'\fR: | |
1019 | .Sp | |
1020 | .Vb 8 | |
1021 | \& sub message { | |
1022 | \& if ( !defined( $_[0] ) ) { | |
1023 | \& print("Hello, World\en"); | |
1024 | \& } | |
1025 | \& else { | |
1026 | \& print( $_[0], "\en" ); | |
1027 | \& } | |
1028 | \& } ## end sub message | |
1029 | .Ve | |
1030 | .Sp | |
1031 | A closing side comment was added for \f(CW\*(C`sub message\*(C'\fR in this case, but not | |
1032 | for the \f(CW\*(C`if\*(C'\fR and \f(CW\*(C`else\*(C'\fR blocks, because they were below the 6 line | |
1033 | cutoff limit for adding closing side comments. This limit may be | |
1034 | changed with the \fB\-csci\fR command, described below. | |
1035 | .Sp | |
1036 | The command \fB\-dcsc\fR (or \fB\-\-delete\-closing\-side\-comments\fR) reverses this | |
1037 | process and removes these comments. | |
1038 | .Sp | |
1039 | Several commands are available to modify the behavior of these two basic | |
1040 | commands, \fB\-csc\fR and \fB\-dcsc\fR: | |
1041 | .RS 4 | |
1042 | .IP "\fB\-csci=n\fR, or \fB\-closing\-side\-comment\-interval=n\fR" 4 | |
1043 | .IX Item "-csci=n, or -closing-side-comment-interval=n" | |
1044 | where \f(CW\*(C`n\*(C'\fR is the minimum number of lines that a block must have in | |
1045 | order for a closing side comment to be added. The default value is | |
1046 | \&\f(CW\*(C`n=6\*(C'\fR. To illustrate: | |
1047 | .Sp | |
1048 | .Vb 9 | |
1049 | \& # perltidy -csci=2 -csc | |
1050 | \& sub message { | |
1051 | \& if ( !defined( $_[0] ) ) { | |
1052 | \& print("Hello, World\en"); | |
1053 | \& } ## end if ( !defined( $_[0] )) | |
1054 | \& else { | |
1055 | \& print( $_[0], "\en" ); | |
1056 | \& } ## end else [ if ( !defined( $_[0] )) | |
1057 | \& } ## end sub message | |
1058 | .Ve | |
1059 | .Sp | |
1060 | Now the \f(CW\*(C`if\*(C'\fR and \f(CW\*(C`else\*(C'\fR blocks are commented. However, now this has | |
1061 | become very cluttered. | |
1062 | .IP "\fB\-cscp=string\fR, or \fB\-closing\-side\-comment\-prefix=string\fR" 4 | |
1063 | .IX Item "-cscp=string, or -closing-side-comment-prefix=string" | |
1064 | where string is the prefix used before the name of the block type. The | |
1065 | default prefix, shown above, is \f(CW\*(C`## end\*(C'\fR. This string will be added to | |
1066 | closing side comments, and it will also be used to recognize them in | |
1067 | order to update, delete, and format them. Any comment identified as a | |
1068 | closing side comment will be placed just a single space to the right of | |
1069 | its closing brace. | |
1070 | .IP "\fB\-cscl=string\fR, or \fB\-closing\-side\-comment\-list\-string\fR" 4 | |
1071 | .IX Item "-cscl=string, or -closing-side-comment-list-string" | |
1072 | where \f(CW\*(C`string\*(C'\fR is a list of block types to be tagged with closing side | |
1073 | comments. By default, all code block types preceded by a keyword or | |
1074 | label (such as \f(CW\*(C`if\*(C'\fR, \f(CW\*(C`sub\*(C'\fR, and so on) will be tagged. The \fB\-cscl\fR | |
1075 | command changes the default list to be any selected block types; see | |
1076 | \&\*(L"Specifying Block Types\*(R". | |
1077 | For example, the following command | |
1078 | requests that only \f(CW\*(C`sub\*(C'\fR's, labels, \f(CW\*(C`BEGIN\*(C'\fR, and \f(CW\*(C`END\*(C'\fR blocks be | |
1079 | affected by any \fB\-csc\fR or \fB\-dcsc\fR operation: | |
1080 | .Sp | |
1081 | .Vb 1 | |
1082 | \& -cscl="sub : BEGIN END" | |
1083 | .Ve | |
1084 | .IP "\fB\-csct=n\fR, or \fB\-closing\-side\-comment\-maximum\-text=n\fR" 4 | |
1085 | .IX Item "-csct=n, or -closing-side-comment-maximum-text=n" | |
1086 | The text appended to certain block types, such as an \f(CW\*(C`if\*(C'\fR block, is | |
1087 | whatever lies between the keyword introducing the block, such as \f(CW\*(C`if\*(C'\fR, | |
1088 | and the opening brace. Since this might be too much text for a side | |
1089 | comment, there needs to be a limit, and that is the purpose of this | |
1090 | parameter. The default value is \f(CW\*(C`n=20\*(C'\fR, meaning that no additional | |
1091 | tokens will be appended to this text after its length reaches 20 | |
1092 | characters. Omitted text is indicated with \f(CW\*(C`...\*(C'\fR. (Tokens, including | |
1093 | sub names, are never truncated, however, so actual lengths may exceed | |
1094 | this). To illustrate, in the above example, the appended text of the | |
1095 | first block is \f(CW\*(C` ( !defined( $_[0] )...\*(C'\fR. The existing limit of | |
1096 | \&\f(CW\*(C`n=20\*(C'\fR caused this text to be truncated, as indicated by the \f(CW\*(C`...\*(C'\fR. | |
1097 | .IP "\fB\-csce=n\fR, or \fB\-closing\-side\-comment\-else\-flag=n\fR" 4 | |
1098 | .IX Item "-csce=n, or -closing-side-comment-else-flag=n" | |
1099 | The default, \fBn=0\fR, places the text of the opening \f(CW\*(C`if\*(C'\fR statement after any | |
1100 | terminal \f(CW\*(C`else\*(C'\fR. | |
1101 | .Sp | |
1102 | If \fBn=2\fR is used, then each \f(CW\*(C`elsif\*(C'\fR is also given the text of the opening | |
1103 | \&\f(CW\*(C`if\*(C'\fR statement. Also, an \f(CW\*(C`else\*(C'\fR will include the text of a preceding | |
1104 | \&\f(CW\*(C`elsif\*(C'\fR statement. Note that this may result some long closing | |
1105 | side comments. | |
1106 | .Sp | |
1107 | If \fBn=1\fR is used, the results will be the same as \fBn=2\fR whenever the | |
1108 | resulting line length is less than the maximum allowed. | |
1109 | .IP "\fB\-cscw\fR, or \fB\-closing\-side\-comment\-warnings\fR" 4 | |
1110 | .IX Item "-cscw, or -closing-side-comment-warnings" | |
1111 | This parameter is intended to help make the initial transition to the use of | |
1112 | closing side comments. | |
1113 | It causes two | |
1114 | things to happen if a closing side comment replaces an existing, different | |
1115 | closing side comment: first, an error message will be issued, and second, the | |
1116 | original side comment will be placed alone on a new specially marked comment | |
1117 | line for later attention. | |
1118 | .Sp | |
1119 | The intent is to avoid clobbering existing hand-written side comments | |
1120 | which happen to match the pattern of closing side comments. This flag | |
1121 | should only be needed on the first run with \fB\-csc\fR. | |
1122 | .RE | |
1123 | .RS 4 | |
1124 | .Sp | |
1125 | \&\fBImportant Notes on Closing Side Comments:\fR | |
1126 | .IP "\(bu" 4 | |
1127 | Closing side comments are only placed on lines terminated with a closing | |
1128 | brace. Certain closing styles, such as the use of cuddled elses | |
1129 | (\fB\-ce\fR), preclude the generation of some closing side comments. | |
1130 | .IP "\(bu" 4 | |
1131 | Please note that adding or deleting of closing side comments takes | |
1132 | place only through the commands \fB\-csc\fR or \fB\-dcsc\fR. The other commands, | |
1133 | if used, merely modify the behavior of these two commands. | |
1134 | .IP "\(bu" 4 | |
1135 | It is recommended that the \fB\-cscw\fR flag be used along with \fB\-csc\fR on | |
1136 | the first use of perltidy on a given file. This will prevent loss of | |
1137 | any existing side comment data which happens to have the csc prefix. | |
1138 | .IP "\(bu" 4 | |
1139 | Once you use \fB\-csc\fR, you should continue to use it so that any | |
1140 | closing side comments remain correct as code changes. Otherwise, these | |
1141 | comments will become incorrect as the code is updated. | |
1142 | .IP "\(bu" 4 | |
1143 | If you edit the closing side comments generated by perltidy, you must also | |
1144 | change the prefix to be different from the closing side comment prefix. | |
1145 | Otherwise, your edits will be lost when you rerun perltidy with \fB\-csc\fR. For | |
1146 | example, you could simply change \f(CW\*(C`## end\*(C'\fR to be \f(CW\*(C`## End\*(C'\fR, since the test is | |
1147 | case sensitive. You may also want to use the \fB\-ssc\fR flag to keep these | |
1148 | modified closing side comments spaced the same as actual closing side comments. | |
1149 | .IP "\(bu" 4 | |
1150 | Temporarily generating closing side comments is a useful technique for | |
1151 | exploring and/or debugging a perl script, especially one written by someone | |
1152 | else. You can always remove them with \fB\-dcsc\fR. | |
1153 | .RE | |
1154 | .RS 4 | |
1155 | .RE | |
1156 | .IP "Static Block Comments" 4 | |
1157 | .IX Item "Static Block Comments" | |
1158 | Static block comments are block comments with a special leading pattern, | |
1159 | \&\f(CW\*(C`##\*(C'\fR by default, which will be treated slightly differently from other | |
1160 | block comments. They effectively behave as if they had glue along their | |
1161 | left and top edges, because they stick to the left edge and previous line | |
1162 | when there is no blank spaces in those places. This option is | |
1163 | particularly useful for controlling how commented code is displayed. | |
1164 | .RS 4 | |
1165 | .IP "\fB\-sbc\fR, \fB\-\-static\-block\-comments\fR" 4 | |
1166 | .IX Item "-sbc, --static-block-comments" | |
1167 | When \fB\-sbc\fR is used, a block comment with a special leading pattern, \f(CW\*(C`##\*(C'\fR by | |
1168 | default, will be treated specially. | |
1169 | .Sp | |
1170 | Comments so identified are treated as follows: | |
1171 | .RS 4 | |
1172 | .IP "\(bu" 4 | |
1173 | If there is no leading space on the line, then the comment will not | |
1174 | be indented, and otherwise it may be, | |
1175 | .IP "\(bu" 4 | |
1176 | no new blank line will be | |
1177 | inserted before such a comment, and | |
1178 | .IP "\(bu" 4 | |
1179 | such a comment will never become | |
1180 | a hanging side comment. | |
1181 | .RE | |
1182 | .RS 4 | |
1183 | .Sp | |
1184 | For example, assuming \f(CW@month_of_year\fR is | |
1185 | left\-adjusted: | |
1186 | .Sp | |
1187 | .Vb 4 | |
1188 | \& @month_of_year = ( # -sbc (default) | |
1189 | \& 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', | |
1190 | \& ## 'Dec', 'Nov' | |
1191 | \& 'Nov', 'Dec'); | |
1192 | .Ve | |
1193 | .Sp | |
1194 | Without this convention, the above code would become | |
1195 | .Sp | |
1196 | .Vb 2 | |
1197 | \& @month_of_year = ( # -nsbc | |
1198 | \& 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', | |
1199 | .Ve | |
1200 | .Sp | |
1201 | .Vb 3 | |
1202 | \& ## 'Dec', 'Nov' | |
1203 | \& 'Nov', 'Dec' | |
1204 | \& ); | |
1205 | .Ve | |
1206 | .Sp | |
1207 | which is not as clear. | |
1208 | The default is to use \fB\-sbc\fR. This may be deactivated with \fB\-nsbc\fR. | |
1209 | .RE | |
1210 | .IP "\fB\-sbcp=string\fR, \fB\-\-static\-block\-comment\-prefix=string\fR" 4 | |
1211 | .IX Item "-sbcp=string, --static-block-comment-prefix=string" | |
1212 | This parameter defines the prefix used to identify static block comments | |
1213 | when the \fB\-sbc\fR parameter is set. The default prefix is \f(CW\*(C`##\*(C'\fR, | |
1214 | corresponding to \f(CW\*(C`\-sbcp=##\*(C'\fR. The first character must be a \f(CW\*(C`#\*(C'\fR | |
1215 | symbol, since this must only match comments. As a simple example, to | |
1216 | identify all comments as static block comments, one would use \f(CW\*(C`\-sbcp=#\*(C'\fR. | |
1217 | .Sp | |
1218 | Please note that \fB\-sbcp\fR merely defines the pattern used to identify static | |
1219 | block comments; it will not be used unless the switch \fB\-sbc\fR is set. Also, | |
1220 | please be aware that this string is used in a perl regular expression which | |
1221 | identifies these comments, so it must enable a valid regular expression to be | |
1222 | formed. | |
1223 | .IP "\fB\-osbc\fR, \fB\-\-outdent\-static\-block\-comments\fR" 4 | |
1224 | .IX Item "-osbc, --outdent-static-block-comments" | |
1225 | The command \fB\-osbc\fR will will cause static block comments to be outdented by 2 | |
1226 | spaces (or whatever \fB\-ci=n\fR has been set to), if possible. | |
1227 | .RE | |
1228 | .RS 4 | |
1229 | .RE | |
1230 | .IP "Static Side Comments" 4 | |
1231 | .IX Item "Static Side Comments" | |
1232 | Static side comments are side comments with a special leading pattern. | |
1233 | This option can be useful for controlling how commented code is displayed | |
1234 | when it is a side comment. | |
1235 | .RS 4 | |
1236 | .IP "\fB\-ssc\fR, \fB\-\-static\-side\-comments\fR" 4 | |
1237 | .IX Item "-ssc, --static-side-comments" | |
1238 | When \fB\-ssc\fR is used, a side comment with a static leading pattern, which is | |
1239 | \&\f(CW\*(C`##\*(C'\fR by default, will be be spaced only a single space from previous | |
1240 | character, and it will not be vertically aligned with other side comments. | |
1241 | .Sp | |
1242 | The default is \fB\-nssc\fR. | |
1243 | .IP "\fB\-sscp=string\fR, \fB\-\-static\-side\-comment\-prefix=string\fR" 4 | |
1244 | .IX Item "-sscp=string, --static-side-comment-prefix=string" | |
1245 | This parameter defines the prefix used to identify static side comments | |
1246 | when the \fB\-ssc\fR parameter is set. The default prefix is \f(CW\*(C`##\*(C'\fR, | |
1247 | corresponding to \f(CW\*(C`\-sscp=##\*(C'\fR. | |
1248 | .Sp | |
1249 | Please note that \fB\-sscp\fR merely defines the pattern used to identify | |
1250 | static side comments; it will not be used unless the switch \fB\-ssc\fR is | |
1251 | set. Also, note that this string is used in a perl regular expression | |
1252 | which identifies these comments, so it must enable a valid regular | |
1253 | expression to be formed. | |
1254 | .RE | |
1255 | .RS 4 | |
1256 | .RE | |
1257 | .Sh "Line Break Control" | |
1258 | .IX Subsection "Line Break Control" | |
1259 | .IP "\fB\-fnl\fR, \fB\-\-freeze\-newlines\fR" 4 | |
1260 | .IX Item "-fnl, --freeze-newlines" | |
1261 | If you do not want any changes to the line breaks in your script, set | |
1262 | \&\fB\-fnl\fR, and they will remain fixed, and the rest of the commands in | |
1263 | this section and sections | |
1264 | \&\*(L"Controlling List Formatting\*(R", | |
1265 | \&\*(L"Retaining or Ignoring Existing Line Breaks\*(R", and | |
1266 | \&\*(L"Blank Line Control\*(R" will be ignored. You may want to use \fB\-noll\fR | |
1267 | with this. | |
1268 | .IP "\fB\-ce\fR, \fB\-\-cuddled\-else\fR" 4 | |
1269 | .IX Item "-ce, --cuddled-else" | |
1270 | Enable the \*(L"cuddled else\*(R" style, in which \f(CW\*(C`else\*(C'\fR and \f(CW\*(C`elsif\*(C'\fR are | |
1271 | follow immediately after the curly brace closing the previous block. | |
1272 | The default is not to use cuddled elses, and is indicated with the flag | |
1273 | \&\fB\-nce\fR or \fB\-\-nocuddled\-else\fR. Here is a comparison of the | |
1274 | alternatives: | |
1275 | .Sp | |
1276 | .Vb 5 | |
1277 | \& if ($task) { | |
1278 | \& yyy(); | |
1279 | \& } else { # -ce | |
1280 | \& zzz(); | |
1281 | \& } | |
1282 | .Ve | |
1283 | .Sp | |
1284 | .Vb 6 | |
1285 | \& if ($task) { | |
1286 | \& yyy(); | |
1287 | \& } | |
1288 | \& else { # -nce (default) | |
1289 | \& zzz(); | |
1290 | \& } | |
1291 | .Ve | |
1292 | .IP "\fB\-bl\fR, \fB\-\-opening\-brace\-on\-new\-line\fR" 4 | |
1293 | .IX Item "-bl, --opening-brace-on-new-line" | |
1294 | Use the flag \fB\-bl\fR to place the opening brace on a new line: | |
1295 | .Sp | |
1296 | .Vb 4 | |
1297 | \& if ( $input_file eq '-' ) # -bl | |
1298 | \& { | |
1299 | \& important_function(); | |
1300 | \& } | |
1301 | .Ve | |
1302 | .Sp | |
1303 | This flag applies to all structural blocks, including sub's (unless | |
1304 | the \fB\-sbl\fR flag is set \*(-- see next item). | |
1305 | .Sp | |
1306 | The default style, \fB\-nbl\fR, places an opening brace on the same line as | |
1307 | the keyword introducing it. For example, | |
1308 | .Sp | |
1309 | .Vb 1 | |
1310 | \& if ( $input_file eq '-' ) { # -nbl (default) | |
1311 | .Ve | |
1312 | .IP "\fB\-sbl\fR, \fB\-\-opening\-sub\-brace\-on\-new\-line\fR" 4 | |
1313 | .IX Item "-sbl, --opening-sub-brace-on-new-line" | |
1314 | The flag \fB\-sbl\fR can be used to override the value of \fB\-bl\fR for | |
1315 | opening sub braces. For example, | |
1316 | .Sp | |
1317 | .Vb 1 | |
1318 | \& perltidy -sbl | |
1319 | .Ve | |
1320 | .Sp | |
1321 | produces this result: | |
1322 | .Sp | |
1323 | .Vb 9 | |
1324 | \& sub message | |
1325 | \& { | |
1326 | \& if (!defined($_[0])) { | |
1327 | \& print("Hello, World\en"); | |
1328 | \& } | |
1329 | \& else { | |
1330 | \& print($_[0], "\en"); | |
1331 | \& } | |
1332 | \& } | |
1333 | .Ve | |
1334 | .Sp | |
1335 | This flag is negated with \fB\-nsbl\fR. If \fB\-sbl\fR is not specified, | |
1336 | the value of \fB\-bl\fR is used. | |
1337 | .IP "\fB\-bli\fR, \fB\-\-brace\-left\-and\-indent\fR" 4 | |
1338 | .IX Item "-bli, --brace-left-and-indent" | |
1339 | The flag \fB\-bli\fR is the same as \fB\-bl\fR but in addition it causes one | |
1340 | unit of continuation indentation ( see \fB\-ci\fR ) to be placed before | |
1341 | an opening and closing block braces. | |
1342 | .Sp | |
1343 | For example, | |
1344 | .Sp | |
1345 | .Vb 4 | |
1346 | \& if ( $input_file eq '-' ) # -bli | |
1347 | \& { | |
1348 | \& important_function(); | |
1349 | \& } | |
1350 | .Ve | |
1351 | .Sp | |
1352 | By default, this extra indentation occurs for blocks of type: | |
1353 | \&\fBif\fR, \fBelsif\fR, \fBelse\fR, \fBunless\fR, \fBfor\fR, \fBforeach\fR, \fBsub\fR, | |
1354 | \&\fBwhile\fR, \fBuntil\fR, and also with a preceding label. The next item | |
1355 | shows how to change this. | |
1356 | .IP "\fB\-blil=s\fR, \fB\-\-brace\-left\-and\-indent\-list=s\fR" 4 | |
1357 | .IX Item "-blil=s, --brace-left-and-indent-list=s" | |
1358 | Use this parameter to change the types of block braces for which the | |
1359 | \&\fB\-bli\fR flag applies; see \*(L"Specifying Block Types\*(R". For example, | |
1360 | \&\fB\-blil='if elsif else'\fR would apply it to only \f(CW\*(C`if/elsif/else\*(C'\fR blocks. | |
1361 | .IP "\fB\-bar\fR, \fB\-\-opening\-brace\-always\-on\-right\fR" 4 | |
1362 | .IX Item "-bar, --opening-brace-always-on-right" | |
1363 | The default style, \fB\-nbl\fR places the opening brace on a new | |
1364 | line if it does not fit on the same line as the opening keyword, like | |
1365 | this: | |
1366 | .Sp | |
1367 | .Vb 5 | |
1368 | \& if ( $bigwasteofspace1 && $bigwasteofspace2 | |
1369 | \& || $bigwasteofspace3 && $bigwasteofspace4 ) | |
1370 | \& { | |
1371 | \& big_waste_of_time(); | |
1372 | \& } | |
1373 | .Ve | |
1374 | .Sp | |
1375 | To force the opening brace to always be on the right, use the \fB\-bar\fR | |
1376 | flag. In this case, the above example becomes | |
1377 | .Sp | |
1378 | .Vb 4 | |
1379 | \& if ( $bigwasteofspace1 && $bigwasteofspace2 | |
1380 | \& || $bigwasteofspace3 && $bigwasteofspace4 ) { | |
1381 | \& big_waste_of_time(); | |
1382 | \& } | |
1383 | .Ve | |
1384 | .Sp | |
1385 | A conflict occurs if both \fB\-bl\fR and \fB\-bar\fR are specified. | |
1386 | .IP "Vertical tightness of non-block curly braces, parentheses, and square brackets." 4 | |
1387 | .IX Item "Vertical tightness of non-block curly braces, parentheses, and square brackets." | |
1388 | These parameters control what shall be called vertical tightness. Here are the | |
1389 | main points: | |
1390 | .RS 4 | |
1391 | .IP "\(bu" 4 | |
1392 | Opening tokens (except for block braces) are controlled by \fB\-vt=n\fR, or | |
1393 | \&\fB\-\-vertical\-tightness=n\fR, where | |
1394 | .Sp | |
1395 | .Vb 4 | |
1396 | \& -vt=0 always break a line after opening token (default). | |
1397 | \& -vt=1 do not break unless this would produce more than one | |
1398 | \& step in indentation in a line. | |
1399 | \& -vt=2 never break a line after opening token | |
1400 | .Ve | |
1401 | .IP "\(bu" 4 | |
1402 | You must also use the \fB\-lp\fR flag when you use the \fB\-vt\fR flag; the | |
1403 | reason is explained below. | |
1404 | .IP "\(bu" 4 | |
1405 | Closing tokens (except for block braces) are controlled by \fB\-vtc=n\fR, or | |
1406 | \&\fB\-\-vertical\-tightness\-closing=n\fR, where | |
1407 | .Sp | |
1408 | .Vb 5 | |
1409 | \& -vtc=0 always break a line before a closing token (default), | |
1410 | \& -vtc=1 do not break before a closing token which is followed | |
1411 | \& by a semicolon or another closing token, and is not in | |
1412 | \& a list environment. | |
1413 | \& -vtc=2 never break before a closing token. | |
1414 | .Ve | |
1415 | .Sp | |
1416 | The rules for \fB\-vtc=1\fR are designed to maintain a reasonable balance | |
1417 | between tightness and readability in complex lists. | |
1418 | .IP "\(bu" 4 | |
1419 | Different controls may be applied to to different token types, | |
1420 | and it is also possible to control block braces; see below. | |
1421 | .IP "\(bu" 4 | |
1422 | Finally, please note that these vertical tightness flags are merely | |
1423 | hints to the formatter, and it cannot always follow them. Things which | |
1424 | make it difficult or impossible include comments, blank lines, blocks of | |
1425 | code within a list, and possibly the lack of the \fB\-lp\fR parameter. | |
1426 | Also, these flags may be ignored for very small lists (2 or 3 lines in | |
1427 | length). | |
1428 | .RE | |
1429 | .RS 4 | |
1430 | .Sp | |
1431 | Here are some examples: | |
1432 | .Sp | |
1433 | .Vb 7 | |
1434 | \& # perltidy -lp -vt=0 -vtc=0 | |
1435 | \& %romanNumerals = ( | |
1436 | \& one => 'I', | |
1437 | \& two => 'II', | |
1438 | \& three => 'III', | |
1439 | \& four => 'IV', | |
1440 | \& ); | |
1441 | .Ve | |
1442 | .Sp | |
1443 | .Vb 6 | |
1444 | \& # perltidy -lp -vt=1 -vtc=0 | |
1445 | \& %romanNumerals = ( one => 'I', | |
1446 | \& two => 'II', | |
1447 | \& three => 'III', | |
1448 | \& four => 'IV', | |
1449 | \& ); | |
1450 | .Ve | |
1451 | .Sp | |
1452 | .Vb 5 | |
1453 | \& # perltidy -lp -vt=1 -vtc=1 | |
1454 | \& %romanNumerals = ( one => 'I', | |
1455 | \& two => 'II', | |
1456 | \& three => 'III', | |
1457 | \& four => 'IV', ); | |
1458 | .Ve | |
1459 | .Sp | |
1460 | The difference between \fB\-vt=1\fR and \fB\-vt=2\fR is shown here: | |
1461 | .Sp | |
1462 | .Vb 6 | |
1463 | \& # perltidy -lp -vt=1 | |
1464 | \& $init->add( | |
1465 | \& mysprintf( "(void)find_threadsv(%s);", | |
1466 | \& cstring( $threadsv_names[ $op->targ ] ) | |
1467 | \& ) | |
1468 | \& ); | |
1469 | .Ve | |
1470 | .Sp | |
1471 | .Vb 5 | |
1472 | \& # perltidy -lp -vt=2 | |
1473 | \& $init->add( mysprintf( "(void)find_threadsv(%s);", | |
1474 | \& cstring( $threadsv_names[ $op->targ ] ) | |
1475 | \& ) | |
1476 | \& ); | |
1477 | .Ve | |
1478 | .Sp | |
1479 | With \fB\-vt=1\fR, the line ending in \f(CW\*(C`add(\*(C'\fR does not combine with the next | |
1480 | line because the next line is not balanced. This can help with | |
1481 | readability, but \fB\-vt=2\fR can be used to ignore this rule. | |
1482 | .Sp | |
1483 | The tightest, and least readable, code is produced with both \f(CW\*(C`\-vt=2\*(C'\fR and | |
1484 | \&\f(CW\*(C`\-vtc=2\*(C'\fR: | |
1485 | .Sp | |
1486 | .Vb 3 | |
1487 | \& # perltidy -lp -vt=2 -vtc=2 | |
1488 | \& $init->add( mysprintf( "(void)find_threadsv(%s);", | |
1489 | \& cstring( $threadsv_names[ $op->targ ] ) ) ); | |
1490 | .Ve | |
1491 | .Sp | |
1492 | Notice how the code in all of these examples collapses vertically as | |
1493 | \&\fB\-vt\fR increases, but the indentation remains unchanged. This is | |
1494 | because perltidy implements the \fB\-vt\fR parameter by first formatting as | |
1495 | if \fB\-vt=0\fR, and then simply overwriting one output line on top of the | |
1496 | next, if possible, to achieve the desired vertical tightness. The | |
1497 | \&\fB\-lp\fR indentation style has been designed to allow this vertical | |
1498 | collapse to occur, which is why it is required for the \fB\-vt\fR parameter. | |
1499 | .Sp | |
1500 | The \fB\-vt=n\fR and \fB\-vtc=n\fR parameters apply to each type of container | |
1501 | token. If desired, vertical tightness controls can be applied | |
1502 | independently to each of the closing container token types. | |
1503 | .Sp | |
1504 | The parameters for controlling parentheses are \fB\-pvt=n\fR or | |
1505 | \&\fB\-\-paren\-vertical\-tightness=n\fR, and \fB\-pcvt=n\fR or | |
1506 | \&\fB\-\-paren\-vertical\-tightness\-closing=n\fR. | |
1507 | .Sp | |
1508 | Likewise, the parameters for square brackets are \fB\-sbvt=n\fR or | |
1509 | \&\fB\-\-square\-bracket\-vertical\-tightness=n\fR, and \fB\-sbcvt=n\fR or | |
1510 | \&\fB\-\-square\-bracket\-vertical\-tightness\-closing=n\fR. | |
1511 | .Sp | |
1512 | Finally, the parameters for controlling non-code block braces are | |
1513 | \&\fB\-bvt=n\fR or \fB\-\-brace\-vertical\-tightness=n\fR, and \fB\-bcvt=n\fR or | |
1514 | \&\fB\-\-brace\-vertical\-tightness\-closing=n\fR. | |
1515 | .Sp | |
1516 | In fact, the parameter \fB\-vt=n\fR is actually just an abbreviation for | |
1517 | \&\fB\-pvt=n \-bvt=n sbvt=n\fR, and likewise \fB\-vtc=n\fR is an abbreviation | |
1518 | for \fB\-pvtc=n \-bvtc=n sbvtc=n\fR. | |
1519 | .RE | |
1520 | .IP "\fB\-bbvt=n\fR or \fB\-\-block\-brace\-vertical\-tightness=n\fR" 4 | |
1521 | .IX Item "-bbvt=n or --block-brace-vertical-tightness=n" | |
1522 | The \fB\-bbvt=n\fR flag is just like the \fB\-vt=n\fR flag but applies | |
1523 | to opening code block braces. | |
1524 | .Sp | |
1525 | .Vb 4 | |
1526 | \& -bbvt=0 break after opening block brace (default). | |
1527 | \& -bbvt=1 do not break unless this would produce more than one | |
1528 | \& step in indentation in a line. | |
1529 | \& -bbvt=2 do not break after opening block brace. | |
1530 | .Ve | |
1531 | .Sp | |
1532 | It is necessary to also use either \fB\-bl\fR or \fB\-bli\fR for this to work, | |
1533 | because, as with other vertical tightness controls, it is implemented by | |
1534 | simply overwriting a line ending with an opening block brace with the | |
1535 | subsequent line. For example: | |
1536 | .Sp | |
1537 | .Vb 10 | |
1538 | \& # perltidy -bli -bbvt=0 | |
1539 | \& if ( open( FILE, "< $File" ) ) | |
1540 | \& { | |
1541 | \& while ( $File = <FILE> ) | |
1542 | \& { | |
1543 | \& $In .= $File; | |
1544 | \& $count++; | |
1545 | \& } | |
1546 | \& close(FILE); | |
1547 | \& } | |
1548 | .Ve | |
1549 | .Sp | |
1550 | .Vb 8 | |
1551 | \& # perltidy -bli -bbvt=1 | |
1552 | \& if ( open( FILE, "< $File" ) ) | |
1553 | \& { while ( $File = <FILE> ) | |
1554 | \& { $In .= $File; | |
1555 | \& $count++; | |
1556 | \& } | |
1557 | \& close(FILE); | |
1558 | \& } | |
1559 | .Ve | |
1560 | .Sp | |
1561 | By default this applies to blocks associated with keywords \fBif\fR, | |
1562 | \&\fBelsif\fR, \fBelse\fR, \fBunless\fR, \fBfor\fR, \fBforeach\fR, \fBsub\fR, \fBwhile\fR, | |
1563 | \&\fBuntil\fR, and also with a preceding label. This can be changed with | |
1564 | the parameter \fB\-bbvtl=string\fR, or | |
1565 | \&\fB\-\-block\-brace\-vertical\-tightness\-list=string\fR, where \fBstring\fR is a | |
1566 | space-separated list of block types. For more information on the | |
1567 | possible values of this string, see \*(L"Specifying Block Types\*(R" | |
1568 | .Sp | |
1569 | For example, if we want to just apply this style to \f(CW\*(C`if\*(C'\fR, | |
1570 | \&\f(CW\*(C`elsif\*(C'\fR, and \f(CW\*(C`else\*(C'\fR blocks, we could use | |
1571 | \&\f(CW\*(C`perltidy \-bli \-bbvt \-bbvtl='if elsif else'\*(C'\fR. | |
1572 | .Sp | |
1573 | There is no vertical tightness control for closing block braces; with | |
1574 | the exception of one-line blocks, they will normally remain on a | |
1575 | separate line. | |
1576 | .IP "\fB\-dnl\fR, \fB\-\-delete\-old\-newlines\fR" 4 | |
1577 | .IX Item "-dnl, --delete-old-newlines" | |
1578 | By default, perltidy first deletes all old line break locations, and then it | |
1579 | looks for good break points to match the desired line length. Use \fB\-ndnl\fR | |
1580 | or \fB\-\-nodelete\-old\-newlines\fR to force perltidy to retain all old line break | |
1581 | points. | |
1582 | .IP "\fB\-anl\fR, \fB\-\-add\-newlines\fR" 4 | |
1583 | .IX Item "-anl, --add-newlines" | |
1584 | By default, perltidy will add line breaks when necessary to create | |
1585 | continuations of long lines and to improve the script appearance. Use | |
1586 | \&\fB\-nanl\fR or \fB\-noadd\-newlines\fR to prevent any new line breaks. | |
1587 | .Sp | |
1588 | This flag does not prevent perltidy from eliminating existing line | |
1589 | breaks; see \fB\-freeze\-newlines\fR to completely prevent changes to line | |
1590 | break points. | |
1591 | .IP "Controlling whether perltidy breaks before or after operators" 4 | |
1592 | .IX Item "Controlling whether perltidy breaks before or after operators" | |
1593 | Two command line parameters provide some control over whether | |
1594 | a line break should be before or after specific token types. | |
1595 | .Sp | |
1596 | \&\fB\-wba=s\fR or \fB\-\-want\-break\-after=s\fR, and | |
1597 | .Sp | |
1598 | \&\fB\-wbb=s\fR or \fB\-\-want\-break\-before=s\fR. | |
1599 | .Sp | |
1600 | These parameters are each followed by a quoted string, \fBs\fR, containing | |
1601 | a list of token types (separated only by spaces). No more than one of each | |
1602 | of these parameters should be specified, because repeating a | |
1603 | command-line parameter always overwrites the previous one before | |
1604 | perltidy ever sees it. | |
1605 | .Sp | |
1606 | By default, perltidy breaks \fBafter\fR these token types: | |
1607 | % + \- * / x != == >= <= =~ !~ < > | & >= < | |
1608 | = **= += *= &= <<= &&= \-= /= |= >>= ||= .= %= ^= x= | |
1609 | .Sp | |
1610 | And perltidy breaks \fBbefore\fR these token types by default: | |
1611 | . << >> \-> && || | |
1612 | .Sp | |
1613 | To illustrate, to cause a break after a concatenation operator, \f(CW'.'\fR, | |
1614 | rather than before it, the command line would be | |
1615 | .Sp | |
1616 | .Vb 1 | |
1617 | \& -wba="." | |
1618 | .Ve | |
1619 | .Sp | |
1620 | As another example, the following command would cause a break before | |
1621 | math operators \f(CW'+'\fR, \f(CW'\-'\fR, \f(CW'/'\fR, and \f(CW'*'\fR: | |
1622 | .Sp | |
1623 | .Vb 1 | |
1624 | \& -wbb="+ - / *" | |
1625 | .Ve | |
1626 | .Sp | |
1627 | These commands should work well for most of the token types that | |
1628 | perltidy uses (use \fB\-\-dump\-token\-types\fR for a list). However, for a | |
1629 | few token types there may be conflicts with hardwired logic which cause | |
1630 | unexpected results. One example is curly braces, which should be | |
1631 | controlled with the parameter \fBbl\fR provided for that purpose. | |
1632 | .Sh "Controlling List Formatting" | |
1633 | .IX Subsection "Controlling List Formatting" | |
1634 | Perltidy attempts to place comma-separated arrays of values in tables | |
1635 | which look good. Its default algorithms usually work well, and they | |
1636 | have been improving with each release, but several parameters are | |
1637 | available to control list formatting. | |
1638 | .IP "\fB\-boc\fR, \fB\-\-break\-at\-old\-comma\-breakpoints\fR" 4 | |
1639 | .IX Item "-boc, --break-at-old-comma-breakpoints" | |
1640 | This flag tells perltidy to try to break at all old commas. This is not | |
1641 | the default. Normally, perltidy makes a best guess at list formatting, | |
1642 | and seldom uses old comma breakpoints. Usually this works well, | |
1643 | but consider: | |
1644 | .Sp | |
1645 | .Vb 5 | |
1646 | \& my @list = (1, | |
1647 | \& 1, 1, | |
1648 | \& 1, 2, 1, | |
1649 | \& 1, 3, 3, 1, | |
1650 | \& 1, 4, 6, 4, 1,); | |
1651 | .Ve | |
1652 | .Sp | |
1653 | The default formatting will flatten this down to one line: | |
1654 | .Sp | |
1655 | .Vb 2 | |
1656 | \& # perltidy (default) | |
1657 | \& my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, ); | |
1658 | .Ve | |
1659 | .Sp | |
1660 | which hides the structure. Using \fB\-boc\fR, plus additional flags | |
1661 | to retain the original style, yields | |
1662 | .Sp | |
1663 | .Vb 6 | |
1664 | \& # perltidy -boc -lp -pt=2 -vt=1 -vtc=1 | |
1665 | \& my @list = (1, | |
1666 | \& 1, 1, | |
1667 | \& 1, 2, 1, | |
1668 | \& 1, 3, 3, 1, | |
1669 | \& 1, 4, 6, 4, 1,); | |
1670 | .Ve | |
1671 | .Sp | |
1672 | A disadvantage of this flag is that all tables in the file | |
1673 | must already be nicely formatted. | |
1674 | .IP "\fB\-mft=n\fR, \fB\-\-maximum\-fields\-per\-table=n\fR" 4 | |
1675 | .IX Item "-mft=n, --maximum-fields-per-table=n" | |
1676 | If the computed number of fields for any table exceeds \fBn\fR, then it | |
1677 | will be reduced to \fBn\fR. The default value for \fBn\fR is a large number, | |
1678 | 40. While this value should probably be left unchanged as a general | |
1679 | rule, it might be used on a small section of code to force a list to | |
1680 | have a particular number of fields per line, and then either the \fB\-boc\fR | |
1681 | flag could be used to retain this formatting, or a single comment could | |
1682 | be introduced somewhere to freeze the formatting in future applications | |
1683 | of perltidy. | |
1684 | .Sp | |
1685 | .Vb 9 | |
1686 | \& # perltidy -mft=2 | |
1687 | \& @month_of_year = ( | |
1688 | \& 'Jan', 'Feb', | |
1689 | \& 'Mar', 'Apr', | |
1690 | \& 'May', 'Jun', | |
1691 | \& 'Jul', 'Aug', | |
1692 | \& 'Sep', 'Oct', | |
1693 | \& 'Nov', 'Dec' | |
1694 | \& ); | |
1695 | .Ve | |
1696 | .IP "\fB\-cab=n\fR, \fB\-\-comma\-arrow\-breakpoints=n\fR" 4 | |
1697 | .IX Item "-cab=n, --comma-arrow-breakpoints=n" | |
1698 | A comma which follows a comma arrow, '=>', requires special | |
1699 | consideration. In a long list, it is common to break at all such | |
1700 | commas. This parameter can be used to control how perltidy breaks at | |
1701 | these commas. (However, it will have no effect if old comma breaks are | |
1702 | being forced because \fB\-boc\fR is used). The possible values of \fBn\fR are: | |
1703 | .Sp | |
1704 | .Vb 6 | |
1705 | \& n=0 break at all commas after => | |
1706 | \& n=1 stable: break at all commas after => unless this would break | |
1707 | \& an existing one-line container (default) | |
1708 | \& n=2 break at all commas after =>, but try to form the maximum | |
1709 | \& maximum one-line container lengths | |
1710 | \& n=3 do not treat commas after => specially at all | |
1711 | .Ve | |
1712 | .Sp | |
1713 | For example, given the following single line, perltidy by default will | |
1714 | not add any line breaks because it would break the existing one-line | |
1715 | container: | |
1716 | .Sp | |
1717 | .Vb 1 | |
1718 | \& bless { B => $B, Root => $Root } => $package; | |
1719 | .Ve | |
1720 | .Sp | |
1721 | Using \fB\-cab=0\fR will force a break after each comma-arrow item: | |
1722 | .Sp | |
1723 | .Vb 5 | |
1724 | \& # perltidy -cab=0: | |
1725 | \& bless { | |
1726 | \& B => $B, | |
1727 | \& Root => $Root | |
1728 | \& } => $package; | |
1729 | .Ve | |
1730 | .Sp | |
1731 | If perltidy is subsequently run with this container broken, then by | |
1732 | default it will break after each '=>' because the container is now | |
1733 | broken. To reform a one-line container, the parameter \fB\-cab=2\fR would | |
1734 | be needed. | |
1735 | .Sp | |
1736 | The flag \fB\-cab=3\fR can be used to prevent these commas from being | |
1737 | treated specially. In this case, an item such as \*(L"01\*(R" => 31 is | |
1738 | treated as a single item in a table. The number of fields in this table | |
1739 | will be determined by the same rules that are used for any other table. | |
1740 | Here is an example. | |
1741 | .Sp | |
1742 | .Vb 6 | |
1743 | \& # perltidy -cab=3 | |
1744 | \& my %last_day = ( | |
1745 | \& "01" => 31, "02" => 29, "03" => 31, "04" => 30, | |
1746 | \& "05" => 31, "06" => 30, "07" => 31, "08" => 31, | |
1747 | \& "09" => 30, "10" => 31, "11" => 30, "12" => 31 | |
1748 | \& ); | |
1749 | .Ve | |
1750 | .Sh "Retaining or Ignoring Existing Line Breaks" | |
1751 | .IX Subsection "Retaining or Ignoring Existing Line Breaks" | |
1752 | Several additional parameters are available for controlling the extent | |
1753 | to which line breaks in the input script influence the output script. | |
1754 | In most cases, the default parameter values are set so that, if a choice | |
1755 | is possible, the output style follows the input style. For example, if | |
1756 | a short logical container is broken in the input script, then the | |
1757 | default behavior is for it to remain broken in the output script. | |
1758 | .PP | |
1759 | Most of the parameters in this section would only be required for a | |
1760 | one-time conversion of a script from short container lengths to longer | |
1761 | container lengths. The opposite effect, of converting long container | |
1762 | lengths to shorter lengths, can be obtained by temporarily using a short | |
1763 | maximum line length. | |
1764 | .IP "\fB\-bol\fR, \fB\-\-break\-at\-old\-logical\-breakpoints\fR" 4 | |
1765 | .IX Item "-bol, --break-at-old-logical-breakpoints" | |
1766 | By default, if a logical expression is broken at a \f(CW\*(C`&&\*(C'\fR, \f(CW\*(C`||\*(C'\fR, \f(CW\*(C`and\*(C'\fR, | |
1767 | or \f(CW\*(C`or\*(C'\fR, then the container will remain broken. Also, breaks | |
1768 | at internal keywords \f(CW\*(C`if\*(C'\fR and \f(CW\*(C`unless\*(C'\fR will normally be retained. | |
1769 | To prevent this, and thus form longer lines, use \fB\-nbol\fR. | |
1770 | .IP "\fB\-bok\fR, \fB\-\-break\-at\-old\-keyword\-breakpoints\fR" 4 | |
1771 | .IX Item "-bok, --break-at-old-keyword-breakpoints" | |
1772 | By default, perltidy will retain a breakpoint before keywords which may | |
1773 | return lists, such as \f(CW\*(C`sort\*(C'\fR and <map>. This allows chains of these | |
1774 | operators to be displayed one per line. Use \fB\-nbok\fR to prevent | |
1775 | retaining these breakpoints. | |
1776 | .IP "\fB\-bot\fR, \fB\-\-break\-at\-old\-trinary\-breakpoints\fR" 4 | |
1777 | .IX Item "-bot, --break-at-old-trinary-breakpoints" | |
1778 | By default, if a conditional (trinary) operator is broken at a \f(CW\*(C`:\*(C'\fR, | |
1779 | then it will remain broken. To prevent this, and thereby | |
1780 | form longer lines, use \fB\-nbot\fR. | |
1781 | .IP "\fB\-iob\fR, \fB\-\-ignore\-old\-breakpoints\fR" 4 | |
1782 | .IX Item "-iob, --ignore-old-breakpoints" | |
1783 | Use this flag to tell perltidy to ignore existing line breaks to the | |
1784 | maximum extent possible. This will tend to produce the longest possible | |
1785 | containers, regardless of type, which do not exceed the line length | |
1786 | limit. | |
1787 | .Sh "Blank Line Control" | |
1788 | .IX Subsection "Blank Line Control" | |
1789 | Blank lines can improve the readability of a script if they are carefully | |
1790 | placed. Perltidy has several commands for controlling the insertion, | |
1791 | retention, and removal of blank lines. | |
1792 | .IP "\fB\-bbc\fR, \fB\-\-blanks\-before\-comments\fR" 4 | |
1793 | .IX Item "-bbc, --blanks-before-comments" | |
1794 | A blank line will be introduced before a full-line comment. This is the | |
1795 | default. Use \fB\-nbbc\fR or \fB\-\-noblanks\-before\-comments\fR to prevent | |
1796 | such blank lines from being introduced. | |
1797 | .IP "\fB\-bbs\fR, \fB\-\-blanks\-before\-subs\fR" 4 | |
1798 | .IX Item "-bbs, --blanks-before-subs" | |
1799 | A blank line will be introduced before a \fBsub\fR definition, unless it is a | |
1800 | one-liner or preceded by a comment. A blank line will also be introduced | |
1801 | before a \fBpackage\fR statement and a \fB\s-1BEGIN\s0\fR and \fB\s-1END\s0\fR block. This is the | |
1802 | default. The intention is to help display the structure of a program by | |
1803 | setting off certain key sections of code. This is negated with \fB\-nbbs\fR or | |
1804 | \&\fB\-\-noblanks\-before\-subs\fR. | |
1805 | .IP "\fB\-bbb\fR, \fB\-\-blanks\-before\-blocks\fR" 4 | |
1806 | .IX Item "-bbb, --blanks-before-blocks" | |
1807 | A blank line will be introduced before blocks of coding delimited by | |
1808 | \&\fBfor\fR, \fBforeach\fR, \fBwhile\fR, \fBuntil\fR, and \fBif\fR, \fBunless\fR, in the following | |
1809 | circumstances: | |
1810 | .RS 4 | |
1811 | .IP "\(bu" 4 | |
1812 | The block is not preceded by a comment. | |
1813 | .IP "\(bu" 4 | |
1814 | The block is not a one-line block. | |
1815 | .IP "\(bu" 4 | |
1816 | The number of consecutive non-blank lines at the current indentation depth is at least \fB\-lbl\fR | |
1817 | (see next section). | |
1818 | .RE | |
1819 | .RS 4 | |
1820 | .Sp | |
1821 | This is the default. The intention of this option is to introduce | |
1822 | some space within dense coding. | |
1823 | This is negated with \fB\-nbbb\fR or \fB\-\-noblanks\-before\-blocks\fR. | |
1824 | .RE | |
1825 | .IP "\fB\-lbl=n\fR \fB\-\-long\-block\-line\-count=n\fR" 4 | |
1826 | .IX Item "-lbl=n --long-block-line-count=n" | |
1827 | This controls how often perltidy is allowed to add blank lines before | |
1828 | certain block types (see previous section). The default is 8. Entering | |
1829 | a value of \fB0\fR is equivalent to entering a very large number. | |
1830 | .IP "\fB\-mbl=n\fR \fB\-\-maximum\-consecutive\-blank\-lines=n\fR" 4 | |
1831 | .IX Item "-mbl=n --maximum-consecutive-blank-lines=n" | |
1832 | This parameter specifies the maximum number of consecutive blank lines | |
1833 | in the output script. The default is n=1. If the input file has more | |
1834 | than n consecutive blank lines, the number will be reduced to n. | |
1835 | (This obviously does not apply to pod sections, here\-documents, and quotes). | |
1836 | .IP "\fB\-sob\fR, \fB\-\-swallow\-optional\-blank\-lines\fR" 4 | |
1837 | .IX Item "-sob, --swallow-optional-blank-lines" | |
1838 | All blank lines not required by the above flags, \fB\-bbb\fR, \fB\-bbs\fR, and \fB\-bbc\fR, | |
1839 | will be deleted. (But essential blank lines above pod documents will be | |
1840 | retained). This is \s-1NOT\s0 the default. | |
1841 | .IP "\fB\-nsob\fR, \fB\-\-noswallow\-optional\-blank\-lines\fR" 4 | |
1842 | .IX Item "-nsob, --noswallow-optional-blank-lines" | |
1843 | Retain blank lines, including those which do not corresponding to flags | |
1844 | \&\fB\-bbb\fR, \fB\-bbs\fR, and \fB\-bbc\fR. This is the default. The number of | |
1845 | blanks retained is subject to the limit imposed by | |
1846 | \&\fB\-\-maximum\-consecutive\-blank\-lines\fR, however. | |
1847 | .Sh "Styles" | |
1848 | .IX Subsection "Styles" | |
1849 | A style refers to a convenient collection of existing parameters. | |
1850 | .IP "\fB\-gnu\fR, \fB\-\-gnu\-style\fR" 4 | |
1851 | .IX Item "-gnu, --gnu-style" | |
1852 | \&\fB\-gnu\fR gives an approximation to the \s-1GNU\s0 Coding Standards (which do | |
1853 | not apply to perl) as they are sometimes implemented. At present, this | |
1854 | style overrides the default style with the following parameters: | |
1855 | .Sp | |
1856 | .Vb 1 | |
1857 | \& -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp | |
1858 | .Ve | |
1859 | .Sh "Other Controls" | |
1860 | .IX Subsection "Other Controls" | |
1861 | .IP "Deleting selected text" 4 | |
1862 | .IX Item "Deleting selected text" | |
1863 | Perltidy can selectively delete comments and/or pod documentation. The | |
1864 | command \fB\-dac\fR or \fB\-\-delete\-all\-comments\fR will delete all comments | |
1865 | \&\fBand\fR all pod documentation, leaving just code and any leading system | |
1866 | control lines. | |
1867 | .Sp | |
1868 | The command \fB\-dp\fR or \fB\-\-delete\-pod\fR will remove all pod documentation | |
1869 | (but not comments). | |
1870 | .Sp | |
1871 | Two commands which remove comments (but not pod) are: \fB\-dbc\fR or | |
1872 | \&\fB\-\-delete\-block\-comments\fR and \fB\-dsc\fR or \fB\-\-delete\-side\-comments\fR. | |
1873 | (Hanging side comments will be deleted with block comments here.) | |
1874 | .Sp | |
1875 | The negatives of these commands also work, and are the defaults. When | |
1876 | block comments are deleted, any leading 'hash\-bang' will be retained. | |
1877 | Also, if the \fB\-x\fR flag is used, any system commands before a leading | |
1878 | hash-bang will be retained (even if they are in the form of comments). | |
1879 | .IP "Writing selected text to a file" 4 | |
1880 | .IX Item "Writing selected text to a file" | |
1881 | When perltidy writes a formatted text file, it has the ability to also | |
1882 | send selected text to a file with a \fI.TEE\fR extension. This text can | |
1883 | include comments and pod documentation. | |
1884 | .Sp | |
1885 | The command \fB\-tac\fR or \fB\-\-tee\-all\-comments\fR will write all comments | |
1886 | \&\fBand\fR all pod documentation. | |
1887 | .Sp | |
1888 | The command \fB\-tp\fR or \fB\-\-tee\-pod\fR will write all pod documentation (but | |
1889 | not comments). | |
1890 | .Sp | |
1891 | The commands which write comments (but not pod) are: \fB\-tbc\fR or | |
1892 | \&\fB\-\-tee\-block\-comments\fR and \fB\-tsc\fR or \fB\-\-tee\-side\-comments\fR. | |
1893 | (Hanging side comments will be written with block comments here.) | |
1894 | .Sp | |
1895 | The negatives of these commands also work, and are the defaults. | |
1896 | .IP "Using a \fI.perltidyrc\fR command file" 4 | |
1897 | .IX Item "Using a .perltidyrc command file" | |
1898 | If you use perltidy frequently, you probably won't be happy until you | |
1899 | create a \fI.perltidyrc\fR file to avoid typing commonly-used parameters. | |
1900 | Perltidy will first look in your current directory for a command file | |
1901 | named \fI.perltidyrc\fR. If it does not find one, it will continue looking | |
1902 | for one in other standard locations. | |
1903 | .Sp | |
1904 | These other locations are system\-dependent, and may be displayed with | |
1905 | the command \f(CW\*(C`perltidy \-dpro\*(C'\fR. Under Unix systems, it will look for a | |
1906 | \&\fI.perltidyrc\fR file in the home directory, and then for a system-wide | |
1907 | file \fI/usr/local/etc/perltidyrc\fR, and then it will look for | |
1908 | \&\fI/etc/perltidyrc\fR. Note that these last two system-wide files do not | |
1909 | have a leading dot. Further system-dependent information will be found | |
1910 | in the \s-1INSTALL\s0 file distributed with perltidy. | |
1911 | .Sp | |
1912 | This file is free format, and simply a list of parameters, just as they | |
1913 | would be entered on a command line. Any number of lines may be used, | |
1914 | with any number of parameters per line, although it may be easiest to | |
1915 | read with one parameter per line. Blank lines are ignored, and text | |
1916 | after a '#' is ignored to the end of a line. | |
1917 | .Sp | |
1918 | Here is an example of a \fI.perltidyrc\fR file: | |
1919 | .Sp | |
1920 | .Vb 8 | |
1921 | \& # This is a simple of a .perltidyrc configuration file | |
1922 | \& # This implements a highly spaced style | |
1923 | \& -se # errors to standard error output | |
1924 | \& -w # show all warnings | |
1925 | \& -bl # braces on new lines | |
1926 | \& -pt=0 # parens not tight at all | |
1927 | \& -bt=0 # braces not tight | |
1928 | \& -sbt=0 # square brackets not tight | |
1929 | .Ve | |
1930 | .Sp | |
1931 | The parameters in the \fI.perltidyrc\fR file are installed first, so any | |
1932 | parameters given on the command line will have priority over them. | |
1933 | .Sp | |
1934 | To avoid confusion, perltidy ignores any command in the .perltidyrc | |
1935 | file which would cause some kind of dump and an exit. These are: | |
1936 | .Sp | |
1937 | .Vb 1 | |
1938 | \& -h -v -ddf -dln -dop -dsn -dtt -dwls -dwrs -ss | |
1939 | .Ve | |
1940 | .Sp | |
1941 | There are several options may be helpful in debugging a \fI.perltidyrc\fR | |
1942 | file: | |
1943 | .RS 4 | |
1944 | .IP "\(bu" 4 | |
1945 | A very helpful command is \fB\-\-dump\-profile\fR or \fB\-dpro\fR. It writes a | |
1946 | list of all configuration filenames tested to standard output, and | |
1947 | if a file is found, it dumps the content to standard output before | |
1948 | exiting. So, to find out where perltidy looks for its configuration | |
1949 | files, and which one if any it selects, just enter | |
1950 | .Sp | |
1951 | .Vb 1 | |
1952 | \& perltidy -dpro | |
1953 | .Ve | |
1954 | .IP "\(bu" 4 | |
1955 | It may be simplest to develop and test configuration files with | |
1956 | alternative names, and invoke them with \fB\-pro=filename\fR on the command | |
1957 | line. Then rename the desired file to \fI.perltidyrc\fR when finished. | |
1958 | .IP "\(bu" 4 | |
1959 | The parameters in the \fI.perltidyrc\fR file can be switched off with | |
1960 | the \fB\-npro\fR option. | |
1961 | .IP "\(bu" 4 | |
1962 | The commands \fB\-dump\-options\fR, \fB\-dump\-defaults\fR, \fB\-dump\-long\-names\fR, | |
1963 | and \fB\-dump\-short\-names\fR, all described below, may all be helpful. | |
1964 | .RE | |
1965 | .RS 4 | |
1966 | .RE | |
1967 | .IP "Creating a new abbreviation" 4 | |
1968 | .IX Item "Creating a new abbreviation" | |
1969 | A special notation is available for use in a \fI.perltidyrc\fR file | |
1970 | for creating an abbreviation for a group | |
1971 | of options. This can be used to create a | |
1972 | shorthand for one or more styles which are frequently, but not always, | |
1973 | used. The notation is to group the options within curly braces which | |
1974 | are preceded by the name of the alias (without leading dashes), like this: | |
1975 | .Sp | |
1976 | .Vb 4 | |
1977 | \& newword { | |
1978 | \& -opt1 | |
1979 | \& -opt2 | |
1980 | \& } | |
1981 | .Ve | |
1982 | .Sp | |
1983 | where \fBnewword\fR is the abbreviation, and \fBopt1\fR, etc, are existing parameters | |
1984 | \&\fIor other abbreviations\fR. The main syntax requirement is that | |
1985 | the new abbreviation must begin on a new line. | |
1986 | Space before and after the curly braces is optional. | |
1987 | For a | |
1988 | specific example, the following line | |
1989 | .Sp | |
1990 | .Vb 1 | |
1991 | \& airy {-bl -pt=0 -bt=0 -sbt=0} | |
1992 | .Ve | |
1993 | .Sp | |
1994 | could be placed in a \fI.perltidyrc\fR file, and then invoked at will with | |
1995 | .Sp | |
1996 | .Vb 1 | |
1997 | \& perltidy -airy somefile.pl | |
1998 | .Ve | |
1999 | .Sp | |
2000 | (Either \f(CW\*(C`\-airy\*(C'\fR or \f(CW\*(C`\-\-airy\*(C'\fR may be used). | |
2001 | .IP "Skipping leading non-perl commands with \fB\-x\fR or \fB\-\-look\-for\-hash\-bang\fR" 4 | |
2002 | .IX Item "Skipping leading non-perl commands with -x or --look-for-hash-bang" | |
2003 | If your script has leading lines of system commands or other text which | |
2004 | are not valid perl code, and which are separated from the start of the | |
2005 | perl code by a \*(L"hash\-bang\*(R" line, ( a line of the form \f(CW\*(C`#!...perl\*(C'\fR ), | |
2006 | you must use the \fB\-x\fR flag to tell perltidy not to parse and format any | |
2007 | lines before the \*(L"hash\-bang\*(R" line. This option also invokes perl with a | |
2008 | \&\-x flag when checking the syntax. This option was originally added to | |
2009 | allow perltidy to parse interactive \s-1VMS\s0 scripts, but it should be used | |
2010 | for any script which is normally invoked with \f(CW\*(C`perl \-x\*(C'\fR. | |
2011 | .IP "Making a file unreadable" 4 | |
2012 | .IX Item "Making a file unreadable" | |
2013 | The goal of perltidy is to improve the readability of files, but there | |
2014 | are two commands which have the opposite effect, \fB\-\-mangle\fR and | |
2015 | \&\fB\-\-extrude\fR. They are actually | |
2016 | merely aliases for combinations of other parameters. Both of these | |
2017 | strip all possible whitespace, but leave comments and pod documents, | |
2018 | so that they are essentially reversible. The | |
2019 | difference between these is that \fB\-\-mangle\fR puts the fewest possible | |
2020 | line breaks in a script while \fB\-\-extrude\fR puts the maximum possible. | |
2021 | Note that these options do not provided any meaningful obfuscation, because | |
2022 | perltidy can be used to reformat the files. They were originally | |
2023 | developed to help test the tokenization logic of perltidy, but they | |
2024 | have other uses. | |
2025 | One use for \fB\-\-mangle\fR is the following: | |
2026 | .Sp | |
2027 | .Vb 1 | |
2028 | \& perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new | |
2029 | .Ve | |
2030 | .Sp | |
2031 | This will form the maximum possible number of one-line blocks (see next | |
2032 | section), and can sometimes help clean up a badly formatted script. | |
2033 | .Sp | |
2034 | A similar technique can be used with \fB\-\-extrude\fR instead of \fB\-\-mangle\fR | |
2035 | to make the minimum number of one-line blocks. | |
2036 | .Sp | |
2037 | Another use for \fB\-\-mangle\fR is to combine it with \fB\-dac\fR to reduce | |
2038 | the file size of a perl script. | |
2039 | .IP "One-line blocks" 4 | |
2040 | .IX Item "One-line blocks" | |
2041 | There are a few points to note regarding one-line blocks. A one-line | |
2042 | block is something like this, | |
2043 | .Sp | |
2044 | .Vb 1 | |
2045 | \& if ($x > 0) { $y = 1 / $x } | |
2046 | .Ve | |
2047 | .Sp | |
2048 | where the contents within the curly braces is short enough to fit | |
2049 | on a single line. | |
2050 | .Sp | |
2051 | With few exceptions, perltidy retains existing one-line blocks, if it | |
2052 | is possible within the line-length constraint, but it does not attempt | |
2053 | to form new ones. In other words, perltidy will try to follow the | |
2054 | one-line block style of the input file. | |
2055 | .Sp | |
2056 | If an existing one-line block is longer than the maximum line length, | |
2057 | however, it will be broken into multiple lines. When this happens, perltidy | |
2058 | checks for and adds any optional terminating semicolon (unless the \fB\-nasc\fR | |
2059 | option is used) if the block is a code block. | |
2060 | .Sp | |
2061 | The main exception is that perltidy will attempt to form new one-line | |
2062 | blocks following the keywords \f(CW\*(C`map\*(C'\fR, \f(CW\*(C`eval\*(C'\fR, and \f(CW\*(C`sort\*(C'\fR, because | |
2063 | these code blocks are often small and most clearly displayed in a single | |
2064 | line. | |
2065 | .Sp | |
2066 | One-line block rules can conflict with the cuddled-else option. When | |
2067 | the cuddled-else option is used, perltidy retains existing one-line | |
2068 | blocks, even if they do not obey cuddled-else formatting. | |
2069 | .Sp | |
2070 | Occasionally, when one-line blocks get broken because they exceed the | |
2071 | available line length, the formatting will violate the requested brace style. | |
2072 | If this happens, reformatting the script a second time should correct | |
2073 | the problem. | |
2074 | .IP "Debugging" 4 | |
2075 | .IX Item "Debugging" | |
2076 | The following flags are available for debugging: | |
2077 | .Sp | |
2078 | \&\fB\-\-dump\-defaults\fR or \fB\-ddf\fR will write the default option set to standard output and quit | |
2079 | .Sp | |
2080 | \&\fB\-\-dump\-profile\fR or \fB\-dpro\fR will write the name of the current | |
2081 | configuration file and its contents to standard output and quit. | |
2082 | .Sp | |
2083 | \&\fB\-\-dump\-options\fR or \fB\-dop\fR will write current option set to standard | |
2084 | output and quit. | |
2085 | .Sp | |
2086 | \&\fB\-\-dump\-long\-names\fR or \fB\-dln\fR will write all command line long names (passed | |
2087 | to Get_options) to standard output and quit. | |
2088 | .Sp | |
2089 | \&\fB\-\-dump\-short\-names\fR or \fB\-dsn\fR will write all command line short names | |
2090 | to standard output and quit. | |
2091 | .Sp | |
2092 | \&\fB\-\-dump\-token\-types\fR or \fB\-dtt\fR will write a list of all token types | |
2093 | to standard output and quit. | |
2094 | .Sp | |
2095 | \&\fB\-\-dump\-want\-left\-space\fR or \fB\-dwls\fR will write the hash \f(CW%want_left_space\fR | |
2096 | to standard output and quit. See the section on controlling whitespace | |
2097 | around tokens. | |
2098 | .Sp | |
2099 | \&\fB\-\-dump\-want\-right\-space\fR or \fB\-dwrs\fR will write the hash \f(CW%want_right_space\fR | |
2100 | to standard output and quit. See the section on controlling whitespace | |
2101 | around tokens. | |
2102 | .Sp | |
2103 | \&\fB\-DEBUG\fR will write a file with extension \fI.DEBUG\fR for each input file | |
2104 | showing the tokenization of all lines of code. | |
2105 | .IP "Working with MakeMaker, AutoLoader and SelfLoader" 4 | |
2106 | .IX Item "Working with MakeMaker, AutoLoader and SelfLoader" | |
2107 | The first \f(CW$VERSION\fR line of a file which might be eval'd by MakeMaker | |
2108 | is passed through unchanged except for indentation. | |
2109 | Use \fB\-\-nopass\-version\-line\fR, or \fB\-npvl\fR, to deactivate this feature. | |
2110 | .Sp | |
2111 | If the AutoLoader module is used, perltidy will continue formatting | |
2112 | code after seeing an _\|_END_\|_ line. | |
2113 | Use \fB\-\-nolook\-for\-autoloader\fR, or \fB\-nlal\fR, to deactivate this feature. | |
2114 | .Sp | |
2115 | Likewise, if the SelfLoader module is used, perltidy will continue formatting | |
2116 | code after seeing a _\|_DATA_\|_ line. | |
2117 | Use \fB\-\-nolook\-for\-selfloader\fR, or \fB\-nlsl\fR, to deactivate this feature. | |
2118 | .IP "Working around problems with older version of Perl" 4 | |
2119 | .IX Item "Working around problems with older version of Perl" | |
2120 | Perltidy contains a number of rules which help avoid known subtleties | |
2121 | and problems with older versions of perl, and these rules always | |
2122 | take priority over whatever formatting flags have been set. For example, | |
2123 | perltidy will usually avoid starting a new line with a bareword, because | |
2124 | this might cause problems if \f(CW\*(C`use strict\*(C'\fR is active. | |
2125 | .Sp | |
2126 | There is no way to override these rules. | |
2127 | .SH "HTML OPTIONS" | |
2128 | .IX Header "HTML OPTIONS" | |
2129 | .IP "The \fB\-html\fR master switch" 4 | |
2130 | .IX Item "The -html master switch" | |
2131 | The flag \fB\-html\fR causes perltidy to write an html file with extension | |
2132 | \&\fI.html\fR. So, for example, the following command | |
2133 | .Sp | |
2134 | .Vb 1 | |
2135 | \& perltidy -html somefile.pl | |
2136 | .Ve | |
2137 | .Sp | |
2138 | will produce a syntax-colored html file named \fIsomefile.pl.html\fR | |
2139 | which may be viewed with a browser. | |
2140 | .Sp | |
2141 | \&\fBPlease Note\fR: In this case, perltidy does not do any formatting to the | |
2142 | input file, and it does not write a formatted file with extension | |
2143 | \&\fI.tdy\fR. This means that two perltidy runs are required to create a | |
2144 | fully reformatted, html copy of a script. | |
2145 | .IP "The \fB\-pre\fR flag for code snippets" 4 | |
2146 | .IX Item "The -pre flag for code snippets" | |
2147 | When the \fB\-pre\fR flag is given, only the pre-formatted section, within | |
2148 | the <\s-1PRE\s0> and </PRE> tags, will be output. This simplifies inclusion | |
2149 | of the output in other files. The default is to output a complete | |
2150 | web page. | |
2151 | .IP "The \fB\-nnn\fR flag for line numbering" 4 | |
2152 | .IX Item "The -nnn flag for line numbering" | |
2153 | When the \fB\-nnn\fR flag is given, the output lines will be numbered. | |
2154 | .IP "The \fB\-toc\fR, or \fB\-\-html\-table\-of\-contents\fR flag" 4 | |
2155 | .IX Item "The -toc, or --html-table-of-contents flag" | |
2156 | By default, a table of contents to packages and subroutines will be | |
2157 | written at the start of html output. Use \fB\-ntoc\fR to prevent this. | |
2158 | This might be useful, for example, for a pod document which contains a | |
2159 | number of unrelated code snippets. This flag only influences the code | |
2160 | table of contents; it has no effect on any table of contents produced by | |
2161 | pod2html (see next item). | |
2162 | .IP "The \fB\-pod\fR, or \fB\-\-pod2html\fR flag" 4 | |
2163 | .IX Item "The -pod, or --pod2html flag" | |
2164 | There are two options for formatting pod documentation. The default is | |
2165 | to pass the pod through the Pod::Html module (which forms the basis of | |
2166 | the pod2html utility). Any code sections are formatted by perltidy, and | |
2167 | the results then merged. Note: perltidy creates a temporary file when | |
2168 | Pod::Html is used; see \*(L"\s-1FILES\s0\*(R". Also, Pod::Html creates temporary | |
2169 | files for its cache. | |
2170 | .Sp | |
2171 | \&\s-1NOTE:\s0 Perltidy counts the number of \f(CW\*(C`=cut\*(C'\fR lines, and either moves the | |
2172 | pod text to the top of the html file if there is one \f(CW\*(C`=cut\*(C'\fR, or leaves | |
2173 | the pod text in its original order (interleaved with code) otherwise. | |
2174 | .Sp | |
2175 | Most of the flags accepted by pod2html may be included in the perltidy | |
2176 | command line, and they will be passed to pod2html. In some cases, | |
2177 | the flags have a prefix \f(CW\*(C`pod\*(C'\fR to emphasize that they are for the | |
2178 | pod2html, and this prefix will be removed before they are passed to | |
2179 | pod2html. The flags which have the additional \f(CW\*(C`pod\*(C'\fR prefix are: | |
2180 | .Sp | |
2181 | .Vb 2 | |
2182 | \& --[no]podheader --[no]podindex --[no]podrecurse --[no]podquiet | |
2183 | \& --[no]podverbose --podflush | |
2184 | .Ve | |
2185 | .Sp | |
2186 | The flags which are unchanged from their use in pod2html are: | |
2187 | .Sp | |
2188 | .Vb 2 | |
2189 | \& --backlink=s --cachedir=s --htmlroot=s --libpods=s --title=s | |
2190 | \& --podpath=s --podroot=s | |
2191 | .Ve | |
2192 | .Sp | |
2193 | where 's' is an appropriate character string. Not all of these flags are | |
2194 | available in older versions of Pod::Html. See your Pod::Html documentation for | |
2195 | more information. | |
2196 | .Sp | |
2197 | The alternative, indicated with \fB\-npod\fR, is not to use Pod::Html, but | |
2198 | rather to format pod text in italics (or whatever the stylesheet | |
2199 | indicates), without special html markup. This is useful, for example, | |
2200 | if pod is being used as an alternative way to write comments. | |
2201 | .IP "The \fB\-frm\fR, or \fB\-\-frames\fR flag" 4 | |
2202 | .IX Item "The -frm, or --frames flag" | |
2203 | By default, a single html output file is produced. This can be changed | |
2204 | with the \fB\-frm\fR option, which creates a frame holding a table of | |
2205 | contents in the left panel and the source code in the right side. This | |
2206 | simplifies code browsing. Assume, for example, that the input file is | |
2207 | \&\fIMyModule.pm\fR. Then, for default file extension choices, these three | |
2208 | files will be created: | |
2209 | .Sp | |
2210 | .Vb 3 | |
2211 | \& MyModule.pm.html - the frame | |
2212 | \& MyModule.pm.toc.html - the table of contents | |
2213 | \& MyModule.pm.src.html - the formatted source code | |
2214 | .Ve | |
2215 | .Sp | |
2216 | Obviously this file naming scheme requires that output be directed to a real | |
2217 | file (as opposed to, say, standard output). If this is not the | |
2218 | case, or if the file extension is unknown, the \fB\-frm\fR option will be | |
2219 | ignored. | |
2220 | .IP "The \fB\-text=s\fR, or \fB\-\-html\-toc\-extension\fR flag" 4 | |
2221 | .IX Item "The -text=s, or --html-toc-extension flag" | |
2222 | Use this flag to specify the extra file extension of the table of contents file | |
2223 | when html frames are used. The default is \*(L"toc\*(R". | |
2224 | See \*(L"Specifying File Extensions\*(R". | |
2225 | .IP "The \fB\-sext=s\fR, or \fB\-\-html\-src\-extension\fR flag" 4 | |
2226 | .IX Item "The -sext=s, or --html-src-extension flag" | |
2227 | Use this flag to specify the extra file extension of the content file when html | |
2228 | frames are used. The default is \*(L"src\*(R". | |
2229 | See \*(L"Specifying File Extensions\*(R". | |
2230 | .IP "The \fB\-hent\fR, or \fB\-\-html\-entities\fR flag" 4 | |
2231 | .IX Item "The -hent, or --html-entities flag" | |
2232 | This flag controls the use of Html::Entities for html formatting. By | |
2233 | default, the module Html::Entities is used to encode special symbols. | |
2234 | This may not be the right thing for some browser/language | |
2235 | combinations. Use \-\-nohtml\-entities or \-nhent to prevent this. | |
2236 | .IP "Style Sheets" 4 | |
2237 | .IX Item "Style Sheets" | |
2238 | Style sheets make it very convenient to control and adjust the | |
2239 | appearance of html pages. The default behavior is to write a page of | |
2240 | html with an embedded style sheet. | |
2241 | .Sp | |
2242 | An alternative to an embedded style sheet is to create a page with a | |
2243 | link to an external style sheet. This is indicated with the | |
2244 | \&\fB\-css=filename\fR, where the external style sheet is \fIfilename\fR. The | |
2245 | external style sheet \fIfilename\fR will be created if and only if it does | |
2246 | not exist. This option is useful for controlling multiple pages from a | |
2247 | single style sheet. | |
2248 | .Sp | |
2249 | To cause perltidy to write a style sheet to standard output and exit, | |
2250 | use the \fB\-ss\fR, or \fB\-\-stylesheet\fR, flag. This is useful if the style | |
2251 | sheet could not be written for some reason, such as if the \fB\-pre\fR flag | |
2252 | was used. Thus, for example, | |
2253 | .Sp | |
2254 | .Vb 1 | |
2255 | \& perltidy -html -ss >mystyle.css | |
2256 | .Ve | |
2257 | .Sp | |
2258 | will write a style sheet with the default properties to file | |
2259 | \&\fImystyle.css\fR. | |
2260 | .Sp | |
2261 | The use of style sheets is encouraged, but a web page without a style | |
2262 | sheets can be created with the flag \fB\-nss\fR. Use this option if you | |
2263 | must to be sure that older browsers (roughly speaking, versions prior to | |
2264 | 4.0 of Netscape Navigator and Internet Explorer) can display the | |
2265 | syntax-coloring of the html files. | |
2266 | .IP "Controlling \s-1HTML\s0 properties" 4 | |
2267 | .IX Item "Controlling HTML properties" | |
2268 | Note: It is usually more convenient to accept the default properties | |
2269 | and then edit the stylesheet which is produced. However, this section | |
2270 | shows how to control the properties with flags to perltidy. | |
2271 | .Sp | |
2272 | Syntax colors may be changed from their default values by flags of the either | |
2273 | the long form, \fB\-html\-color\-xxxxxx=n\fR, or more conveniently the short form, | |
2274 | \&\fB\-hcx=n\fR, where \fBxxxxxx\fR is one of the following words, and \fBx\fR is the | |
2275 | corresponding abbreviation: | |
2276 | .Sp | |
2277 | .Vb 19 | |
2278 | \& Token Type xxxxxx x | |
2279 | \& ---------- -------- -- | |
2280 | \& comment comment c | |
2281 | \& number numeric n | |
2282 | \& identifier identifier i | |
2283 | \& bareword, function bareword w | |
2284 | \& keyword keyword k | |
2285 | \& quite, pattern quote q | |
2286 | \& here doc text here-doc-text h | |
2287 | \& here doc target here-doc-target hh | |
2288 | \& punctuation punctuation pu | |
2289 | \& parentheses paren p | |
2290 | \& structural braces structure s | |
2291 | \& semicolon semicolon sc | |
2292 | \& colon colon co | |
2293 | \& comma comma cm | |
2294 | \& label label j | |
2295 | \& sub definition name subroutine m | |
2296 | \& pod text pod-text pd | |
2297 | .Ve | |
2298 | .Sp | |
2299 | A default set of colors has been defined, but they may be changed by providing | |
2300 | values to any of the following parameters, where \fBn\fR is either a 6 digit | |
2301 | hex \s-1RGB\s0 color value or an ascii name for a color, such as 'red'. | |
2302 | .Sp | |
2303 | To illustrate, the following command will produce an html | |
2304 | file \fIsomefile.pl.html\fR with \*(L"aqua\*(R" keywords: | |
2305 | .Sp | |
2306 | .Vb 1 | |
2307 | \& perltidy -html -hck=00ffff somefile.pl | |
2308 | .Ve | |
2309 | .Sp | |
2310 | and this should be equivalent for most browsers: | |
2311 | .Sp | |
2312 | .Vb 1 | |
2313 | \& perltidy -html -hck=aqua somefile.pl | |
2314 | .Ve | |
2315 | .Sp | |
2316 | Perltidy merely writes any non-hex names that it sees in the html file. | |
2317 | The following 16 color names are defined in the \s-1HTML\s0 3.2 standard: | |
2318 | .Sp | |
2319 | .Vb 16 | |
2320 | \& black => 000000, | |
2321 | \& silver => c0c0c0, | |
2322 | \& gray => 808080, | |
2323 | \& white => ffffff, | |
2324 | \& maroon => 800000, | |
2325 | \& red => ff0000, | |
2326 | \& purple => 800080, | |
2327 | \& fuchsia => ff00ff, | |
2328 | \& green => 008000, | |
2329 | \& lime => 00ff00, | |
2330 | \& olive => 808000, | |
2331 | \& yellow => ffff00 | |
2332 | \& navy => 000080, | |
2333 | \& blue => 0000ff, | |
2334 | \& teal => 008080, | |
2335 | \& aqua => 00ffff, | |
2336 | .Ve | |
2337 | .Sp | |
2338 | Many more names are supported in specific browsers, but it is safest | |
2339 | to use the hex codes for other colors. Helpful color tables can be | |
2340 | located with an internet search for \*(L"\s-1HTML\s0 color tables\*(R". | |
2341 | .Sp | |
2342 | Besides color, two other character attributes may be set: bold, and italics. | |
2343 | To set a token type to use bold, use the flag | |
2344 | \&\fB\-html\-bold\-xxxxxx\fR or \fB\-hbx\fR, where \fBxxxxxx\fR or \fBx\fR are the long | |
2345 | or short names from the above table. Conversely, to set a token type to | |
2346 | \&\s-1NOT\s0 use bold, use \fB\-nohtml\-bold\-xxxxxx\fR or \fB\-nhbx\fR. | |
2347 | .Sp | |
2348 | Likewise, to set a token type to use an italic font, use the flag | |
2349 | \&\fB\-html\-italic\-xxxxxx\fR or \fB\-hix\fR, where again \fBxxxxxx\fR or \fBx\fR are the | |
2350 | long or short names from the above table. And to set a token type to | |
2351 | \&\s-1NOT\s0 use italics, use \fB\-nohtml\-italic\-xxxxxx\fR or \fB\-nhix\fR. | |
2352 | .Sp | |
2353 | For example, to use bold braces and lime color, non\-bold, italics keywords the | |
2354 | following command would be used: | |
2355 | .Sp | |
2356 | .Vb 1 | |
2357 | \& perltidy -html -hbs -hck=00FF00 -nhbk -hik somefile.pl | |
2358 | .Ve | |
2359 | .Sp | |
2360 | The background color can be specified with \fB\-html\-color\-background=n\fR, | |
2361 | or \fB\-hcbg=n\fR for short, where n is a 6 character hex \s-1RGB\s0 value. The | |
2362 | default color of text is the value given to \fBpunctuation\fR, which is | |
2363 | black as a default. | |
2364 | .Sp | |
2365 | Here are some notes and hints: | |
2366 | .Sp | |
2367 | 1. If you find a preferred set of these parameters, you may want | |
2368 | to create a \fI.perltidyrc\fR file containing them. See the perltidy man | |
2369 | page for an explanation. | |
2370 | .Sp | |
2371 | 2. Rather than specifying values for these parameters, it is probably | |
2372 | easier to accept the defaults and then edit a style sheet. The style | |
2373 | sheet contains comments which should make this easy. | |
2374 | .Sp | |
2375 | 3. The syntax-colored html files can be very large, so it may be best to | |
2376 | split large files into smaller pieces to improve download times. | |
2377 | .SH "SOME COMMON INPUT CONVENTIONS" | |
2378 | .IX Header "SOME COMMON INPUT CONVENTIONS" | |
2379 | .Sh "Specifying Block Types" | |
2380 | .IX Subsection "Specifying Block Types" | |
2381 | Several parameters which refer to code block types may be customized by also | |
2382 | specifying an associated list of block types. The type of a block is the name | |
2383 | of the keyword which introduces that block, such as \fBif\fR, \fBelse\fR, or \fBsub\fR. | |
2384 | An exception is a labeled block, which has no keyword, and should be specified | |
2385 | with just a colon. | |
2386 | .PP | |
2387 | For example, the following parameter specifies \f(CW\*(C`sub\*(C'\fR, labels, \f(CW\*(C`BEGIN\*(C'\fR, and | |
2388 | \&\f(CW\*(C`END\*(C'\fR blocks: | |
2389 | .PP | |
2390 | .Vb 1 | |
2391 | \& -cscl="sub : BEGIN END" | |
2392 | .Ve | |
2393 | .PP | |
2394 | (the meaning of the \-cscl parameter is described above.) Note that | |
2395 | quotes are required around the list of block types because of the | |
2396 | spaces. | |
2397 | .Sh "Specifying File Extensions" | |
2398 | .IX Subsection "Specifying File Extensions" | |
2399 | Several parameters allow default file extensions to be overridden. For | |
2400 | example, a backup file extension may be specified with \fB\-bext=ext\fR, | |
2401 | where \fBext\fR is some new extension. In order to provides the user some | |
2402 | flexibility, the following convention is used in all cases to decide if | |
2403 | a leading '.' should be used. If the extension \f(CW\*(C`ext\*(C'\fR begins with | |
2404 | \&\f(CW\*(C`A\-Z\*(C'\fR, \f(CW\*(C`a\-z\*(C'\fR, or \f(CW\*(C`0\-9\*(C'\fR, then it will be appended to the filename with | |
2405 | an intermediate '.' (or perhaps an '_' on \s-1VMS\s0 systems). Otherwise, it | |
2406 | will be appended directly. | |
2407 | .PP | |
2408 | For example, suppose the file is \fIsomefile.pl\fR. For \f(CW\*(C`\-bext=old\*(C'\fR, a '.' is | |
2409 | added to give \fIsomefile.pl.old\fR. For \f(CW\*(C`\-bext=.old\*(C'\fR, no additional '.' is | |
2410 | added, so again the backup file is \fIsomefile.pl.old\fR. For \f(CW\*(C`\-bext=~\*(C'\fR, then no | |
2411 | dot is added, and the backup file will be \fIsomefile.pl~\fR . | |
2412 | .SH "SWITCHES WHICH MAY BE NEGATED" | |
2413 | .IX Header "SWITCHES WHICH MAY BE NEGATED" | |
2414 | The following list shows all short parameter names which allow a prefix | |
2415 | \&'n' to produce the negated form: | |
2416 | .PP | |
2417 | .Vb 5 | |
2418 | \& D anl asc aws b bbb bbc bbs bli boc bok bol bot syn ce csc | |
2419 | \& dac dbc dcsc dnl dws dp dpro dsm dsc ddf dln dop dsn dtt dwls dwrs | |
2420 | \& f fll frm hsc html ibc icb icp iob isbc lp log lal x lsl ple pod bl | |
2421 | \& sbl okw ola oll ple pvl q opt sbc sfs ssc sts se st sob | |
2422 | \& t tac tbc toc tp tsc tqw w | |
2423 | .Ve | |
2424 | .PP | |
2425 | Equivalently, the prefix 'no' or 'no\-' on the corresponding long names may be | |
2426 | used. | |
2427 | .SH "LIMITATIONS" | |
2428 | .IX Header "LIMITATIONS" | |
2429 | .IP "Parsing Limitations" 4 | |
2430 | .IX Item "Parsing Limitations" | |
2431 | Perltidy should work properly on most perl scripts. It does a lot of | |
2432 | self\-checking, but still, it is possible that an error could be | |
2433 | introduced and go undetected. Therefore, it is essential to make | |
2434 | careful backups and to test reformatted scripts. | |
2435 | .Sp | |
2436 | The main current limitation is that perltidy does not scan modules | |
2437 | included with 'use' statements. This makes it necessary to guess the | |
2438 | context of any bare words introduced by such modules. Perltidy has good | |
2439 | guessing algorithms, but they are not infallible. When it must guess, | |
2440 | it leaves a message in the log file. | |
2441 | .Sp | |
2442 | If you encounter a bug, please report it. | |
2443 | .IP "What perltidy does not parse and format" 4 | |
2444 | .IX Item "What perltidy does not parse and format" | |
2445 | Perltidy indents but does not reformat comments and \f(CW\*(C`qw\*(C'\fR quotes. | |
2446 | Perltidy does not in any way modify the contents of here documents or | |
2447 | quoted text, even if they contain source code. (You could, however, | |
2448 | reformat them separately). Perltidy does not format 'format' sections | |
2449 | in any way. And, of course, it does not modify pod documents. | |
2450 | .SH "FILES" | |
2451 | .IX Header "FILES" | |
2452 | .IP "Temporary files" 4 | |
2453 | .IX Item "Temporary files" | |
2454 | Under the \-html option with the default \-\-pod2html flag, a temporary file is | |
2455 | required to pass text to Pod::Html. Unix systems will try to use the \s-1POSIX\s0 | |
2456 | \&\fItmpnam()\fR function. Otherwise the file \fIperltidy.TMP\fR will be temporarily | |
2457 | created in the current working directory. | |
2458 | .IP "Special files when standard input is used" 4 | |
2459 | .IX Item "Special files when standard input is used" | |
2460 | When standard input is used, the log file, if saved, is \fIperltidy.LOG\fR, | |
2461 | and any errors are written to \fIperltidy.ERR\fR unless the \fB\-se\fR flag is | |
2462 | set. These are saved in the current working directory. | |
2463 | .IP "Files overwritten" 4 | |
2464 | .IX Item "Files overwritten" | |
2465 | The following file extensions are used by perltidy, and files with these | |
2466 | extensions may be overwritten or deleted: \fI.ERR\fR, \fI.LOG\fR, \fI.TEE\fR, | |
2467 | and/or \fI.tdy\fR, \fI.html\fR, and \fI.bak\fR, depending on the run type and | |
2468 | settings. | |
2469 | .IP "Files extensions limitations" 4 | |
2470 | .IX Item "Files extensions limitations" | |
2471 | Perltidy does not operate on files for which the run could produce a file with | |
2472 | a duplicated file extension. These extensions include \fI.LOG\fR, \fI.ERR\fR, | |
2473 | \&\fI.TEE\fR, and perhaps \fI.tdy\fR and \fI.bak\fR, depending on the run type. The | |
2474 | purpose of this rule is to prevent generating confusing filenames such as | |
2475 | \&\fIsomefile.tdy.tdy.tdy\fR. | |
2476 | .SH "SEE ALSO" | |
2477 | .IX Header "SEE ALSO" | |
2478 | \&\fIperlstyle\fR\|(1), \fIPerl::Tidy\fR\|(3) | |
2479 | .SH "VERSION" | |
2480 | .IX Header "VERSION" | |
2481 | This man page documents perltidy version 20031021. | |
2482 | .SH "CREDITS" | |
2483 | .IX Header "CREDITS" | |
2484 | Michael Cartmell supplied code for adaptation to \s-1VMS\s0 and helped with | |
2485 | v\-strings. | |
2486 | .PP | |
2487 | Yves Orton supplied code for adaptation to the various versions | |
2488 | of Windows. | |
2489 | .PP | |
2490 | Axel Rose supplied a patch for MacPerl. | |
2491 | .PP | |
2492 | Hugh S. Myers designed and implemented the initial Perl::Tidy module interface. | |
2493 | .PP | |
2494 | Many others have supplied key ideas, suggestions, and bug reports; | |
2495 | see the \s-1CHANGES\s0 file. | |
2496 | .SH "AUTHOR" | |
2497 | .IX Header "AUTHOR" | |
2498 | .Vb 3 | |
2499 | \& Steve Hancock | |
2500 | \& email: perltidy at users.sourceforge.net | |
2501 | \& http://perltidy.sourceforge.net | |
2502 | .Ve | |
2503 | .SH "COPYRIGHT" | |
2504 | .IX Header "COPYRIGHT" | |
2505 | Copyright (c) 2000\-2003 by Steve Hancock | |
2506 | .SH "LICENSE" | |
2507 | .IX Header "LICENSE" | |
2508 | This package is free software; you can redistribute it and/or modify it | |
2509 | under the terms of the \*(L"\s-1GNU\s0 General Public License\*(R". | |
2510 | .PP | |
2511 | Please refer to the file \*(L"\s-1COPYING\s0\*(R" for details. | |
2512 | .SH "DISCLAIMER" | |
2513 | .IX Header "DISCLAIMER" | |
2514 | This package is distributed in the hope that it will be useful, | |
2515 | but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of | |
2516 | \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. | |
2517 | .PP | |
2518 | See the \*(L"\s-1GNU\s0 General Public License\*(R" for more details. |