.\" ========================================================================
.\"
.IX Title "PERLTIDY 1"
-.TH PERLTIDY 1 "2013-09-22" "perl v5.14.2" "User Contributed Perl Documentation"
+.TH PERLTIDY 1 "2017-05-21" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
Perltidy will pass your string to perl with the exception that it will
add a \fB\-c\fR and \fB\-x\fR if appropriate. The \fI.LOG\fR file will show
exactly what flags were passed to perl.
+.IP "\fB\-xs\fR, \fB\-\-extended\-syntax\fR" 4
+.IX Item "-xs, --extended-syntax"
+A problem with formatting Perl code is that some modules can introduce new
+syntax. This flag allows perltidy to handle certain common extensions
+to the standard syntax without complaint.
+.Sp
+For example, without this flag a structure such as the following would generate
+a syntax error and the braces would not be balanced:
+.Sp
+.Vb 3
+\& method deposit( Num $amount) {
+\& $self\->balance( $self\->balance + $amount );
+\& }
+.Ve
+.Sp
+This flag is enabled by default but it can be deactivated with \fB\-nxs\fR.
+Probably the only reason to deactivate this flag is to generate more diagnostic
+messages when debugging a script.
.IP "\fB\-io\fR, \fB\-\-indent\-only\fR" 4
.IX Item "-io, --indent-only"
-This flag is used to deactivate all formatting and line break changes
+This flag is used to deactivate all whitespace and line break changes
within non-blank lines of code.
When it is in effect, the only change to the script will be
-to the indentation and blank lines.
+to the indentation and to the number of blank lines.
And any flags controlling whitespace and newlines will be ignored. You
might want to use this if you are perfectly happy with your whitespace
and line breaks, and merely want perltidy to handle the indentation.
.Sp
If you also want to keep your existing blank lines exactly
as they are, you can add \fB\-\-freeze\-blank\-lines\fR.
+.Sp
+With this option perltidy is still free to modify the indenting (and
+outdenting) of code and comments as it normally would. If you also want to
+prevent long comment lines from being outdented, you can add either \fB\-noll\fR or
+\&\fB\-l=0\fR.
+.Sp
+Setting this flag will prevent perltidy from doing any special operations on
+closing side comments. You may still delete all side comments however when
+this flag is in effect.
+.IP "\fB\-enc=s\fR, \fB\-\-character\-encoding=s\fR" 4
+.IX Item "-enc=s, --character-encoding=s"
+where \fBs\fR=\fBnone\fR or \fButf8\fR. This flag tells perltidy the character encoding
+of both the input and output character streams. The value \fButf8\fR causes the
+stream to be read and written as \s-1UTF\-8\s0. The value \fBnone\fR causes the stream to
+be processed without special encoding assumptions. At present there is no
+automatic detection of character encoding (even if there is a \f(CW\*(Aquse utf8\*(Aq\fR
+statement in your code) so this flag must be set for streams encoded in \s-1UTF\-8\s0.
+Incorrectly setting this parameter can cause data corruption, so please
+carefully check the output.
+.Sp
+The default is \fBnone\fR.
+.Sp
+The abbreviations \fB\-utf8\fR or \fB\-UTF8\fR are equivalent to \fB\-enc=utf8\fR.
+So to process a file named \fBfile.pl\fR which is encoded in \s-1UTF\-8\s0 you can use:
+.Sp
+.Vb 1
+\& perltidy \-utf8 file.pl
+.Ve
.IP "\fB\-ole=s\fR, \fB\-\-output\-line\-ending=s\fR" 4
.IX Item "-ole=s, --output-line-ending=s"
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
.IP "\fB\-blbp=n\fR, \fB\-\-blank\-lines\-before\-packages=n\fR" 4
.IX Item "-blbp=n, --blank-lines-before-packages=n"
The parameter \fB\-blbp=n\fR requests that least \fBn\fR blank lines precede a package
-which does not follow a comment. The default is <\-blbp=1>.
+which does not follow a comment. The default is \fB\-blbp=1\fR.
.Sp
This parameter interacts with the value \fBk\fR of the parameter
\&\fB\-\-maximum\-consecutive\-blank\-lines=k\fR (\fB\-mbl=k\fR) in the same way as described
This controls how often perltidy is allowed to add blank lines before
certain block types (see previous section). The default is 8. Entering
a value of \fB0\fR is equivalent to entering a very large number.
+.IP "\fB\-blao=i\fR or \fB\-\-blank\-lines\-after\-opening\-block=i\fR" 4
+.IX Item "-blao=i or --blank-lines-after-opening-block=i"
+This control places a minimum of \fBi\fR blank lines \fBafter\fR a line which \fBends\fR
+with an opening block brace of a specified type. By default, this only applies
+to the block of a named \fBsub\fR, but this can be changed (see \fB\-blaol\fR below).
+The default is not to do this (\fBi=0\fR).
+.Sp
+Please see the note below on using the \fB\-blao\fR and \fB\-blbc\fR options.
+.IP "\fB\-blbc=i\fR or \fB\-\-blank\-lines\-before\-closing\-block=i\fR" 4
+.IX Item "-blbc=i or --blank-lines-before-closing-block=i"
+This control places a minimum of \fBi\fR blank lines \fBbefore\fR a line which
+\&\fBbegins\fR with a closing block brace of a specified type. By default, this
+only applies to the block of a named \fBsub\fR, but this can be changed (see
+\&\fB\-blbcl\fR below). The default is not to do this (\fBi=0\fR).
+.IP "\fB\-blaol=s\fR or \fB\-\-blank\-lines\-after\-opening\-block\-list=s\fR" 4
+.IX Item "-blaol=s or --blank-lines-after-opening-block-list=s"
+The parameter \fBs\fR is a list of block type keywords to which the flag \fB\-blao\fR
+should apply. The section \*(L"Specifying Block Types\*(R" explains how to list
+block types.
+.IP "\fB\-blbcl=s\fR or \fB\-\-blank\-lines\-before\-closing\-block\-list=s\fR" 4
+.IX Item "-blbcl=s or --blank-lines-before-closing-block-list=s"
+This parameter is a list of block type keywords to which the flag \fB\-blbc\fR
+should apply. The section \*(L"Specifying Block Types\*(R" explains how to list
+block types.
+.IP "Note on using the \fB\-blao\fR and \fB\-blbc\fR options." 4
+.IX Item "Note on using the -blao and -blbc options."
+These blank line controls introduce a certain minimum number of blank lines in
+the text, but the final number of blank lines may be greater, depending on
+values of the other blank line controls and the number of old blank lines. A
+consequence is that introducing blank lines with these and other controls
+cannot be exactly undone, so some experimentation with these controls is
+recommended before using them.
+.Sp
+For example, suppose that for some reason we decide to introduce one blank
+space at the beginning and ending of all blocks. We could do
+this using
+.Sp
+.Vb 1
+\& perltidy \-blao=2 \-blbc=2 \-blaol=\*(Aq*\*(Aq \-blbcl=\*(Aq*\*(Aq filename
+.Ve
+.Sp
+Now suppose the script continues to be developed, but at some later date we
+decide we don't want these spaces after all. we might expect that running with
+the flags \fB\-blao=0\fR and \fB\-blbc=0\fR will undo them. However, by default
+perltidy retains single blank lines, so the blank lines remain.
+.Sp
+We can easily fix this by telling perltidy to ignore old blank lines by
+including the added parameter \fB\-kbl=0\fR and rerunning. Then the unwanted blank
+lines will be gone. However, this will cause all old blank lines to be
+ignored, perhaps even some that were added by hand to improve formatting. So
+please be cautious when using these parameters.
.IP "\fB\-mbl=n\fR \fB\-\-maximum\-consecutive\-blank\-lines=n\fR" 4
.IX Item "-mbl=n --maximum-consecutive-blank-lines=n"
This parameter specifies the maximum number of consecutive blank lines which
.Ve
.Sp
where \fBnewword\fR is the abbreviation, and \fBopt1\fR, etc, are existing parameters
-\&\fIor other abbreviations\fR. The main syntax requirement is that
-the new abbreviation must begin on a new line.
+\&\fIor other abbreviations\fR. The main syntax requirement is that the new
+abbreviation along with its opening curly brace must begin on a new line.
Space before and after the curly braces is optional.
For a
specific example, the following line
An exception is a labeled block, which has no keyword, and should be specified
with just a colon. To specify all blocks use \fB'*'\fR.
.PP
+The keyword \fBsub\fR indicates a named sub. For anonymous subs, use the special
+keyword \fBasub\fR.
+.PP
For example, the following parameter specifies \f(CW\*(C`sub\*(C'\fR, labels, \f(CW\*(C`BEGIN\*(C'\fR, and
\&\f(CW\*(C`END\*(C'\fR blocks:
.PP
\&\fIperlstyle\fR\|(1), \fIPerl::Tidy\fR\|(3)
.SH "VERSION"
.IX Header "VERSION"
-This man page documents perltidy version 20130922.
-.SH "CREDITS"
-.IX Header "CREDITS"
-Michael Cartmell supplied code for adaptation to \s-1VMS\s0 and helped with
-v\-strings.
-.PP
-Yves Orton supplied code for adaptation to the various versions
-of Windows.
+This man page documents perltidy version 20170521.
+.SH "BUG REPORTS"
+.IX Header "BUG REPORTS"
+A list of current bugs and issues can be found at the \s-1CPAN\s0 site
.PP
-Axel Rose supplied a patch for MacPerl.
-.PP
-Hugh S. Myers designed and implemented the initial Perl::Tidy module interface.
-.PP
-Many others have supplied key ideas, suggestions, and bug reports;
-see the \s-1CHANGES\s0 file.
-.SH "AUTHOR"
-.IX Header "AUTHOR"
-.Vb 3
-\& Steve Hancock
-\& email: perltidy at users.sourceforge.net
-\& http://perltidy.sourceforge.net
+.Vb 1
+\& https://rt.cpan.org/Public/Dist/Display.html?Name=Perl\-Tidy
.Ve
+.PP
+To report a new bug or problem, use the link on this page.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
-Copyright (c) 2000\-2012 by Steve Hancock
+Copyright (c) 2000\-2017 by Steve Hancock
.SH "LICENSE"
.IX Header "LICENSE"
This package is free software; you can redistribute it and/or modify it
projects / perltidy.git / blobdiff