diff options
| -rw-r--r-- | share/man/man7/style.perl.7 | 246 |
1 files changed, 0 insertions, 246 deletions
diff --git a/share/man/man7/style.perl.7 b/share/man/man7/style.perl.7 deleted file mode 100644 index 9515da2..0000000 --- a/share/man/man7/style.perl.7 +++ /dev/null @@ -1,246 +0,0 @@ -.\" Copyright (c) 2000 Josef Karthauser <joe@FreeBSD.org> -.\" All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL [your name] OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" $FreeBSD$ -.\" -.Dd October 16, 2000 -.Dt STYLE.PERL 7 -.Os -.Sh NAME -.Nm style.perl -.Nd "FreeBSD Perl source file style guide" -.Sh DESCRIPTION -This file specifies the preferred style for perl scripts in the -.Fx -source tree. -.Bd -literal -# -# Style guide for Perl. Based on the kernel style guide. -# - -# -# VERY important single-line comments look like this. -# - -# Most single-line comments look like this. - -# Multi-line comments look like this. Make them real sentences. -# Fill them so they look like real paragraphs. -.Ed -.Pp -All scripts should follow the copyright block at the start of the -script with a comment block that describes what the script does. -.Bd -literal -#!/usr/bin/perl -w - -# COPYRIGHT -# BLOCK - -# This script processes an old kernel config file, which it gets on -# stdin, and outputs a new style hints file to stdout. -.Ed -.Pp -All scripts should use the -.Xr strict 3 -module and run without warnings. -For example: -.Bd -literal -#!/usr/bin/perl -w - -# Copyright, description of what the script does, etc - -use strict; -\&... -.Ed -.Pp -Where possible run the script with taint mode switched on. -This is documented in -.Xr perlsec 1 . -.Bd -literal -#!/usr/bin/perl -wT -.Ed -.Pp -The main program should be placed in a block labeled MAIN:. -This -makes it easier to identify the entry point in a large perl script, -and provides a scope for variables which are used in the main -program but nowhere else. -.Bd -literal -MAIN:{ - print(foo("/usr/bin/man", "7", "style.perl")); - exit(0); -} -.Ed -.Pp -All subroutines should be defined using argument prototypes as defined in -.Xr perlsub 1 . -.Bd -literal -sub foo($@) { - my $cmd = shift; - my @args = @_; -} -.Ed -.Pp -All variables should be defined before use; this is enforced if operating -under -.Ic use Ar strict . -.Pp -Scope local variables should be defined using -.Ic my -.Va $variable -and not -.Ic local -.Va $variable . -The -.Ic local -declaration should only be used when it is required, and not by -default. -Lots of perl4 scripts use -.Ic local -because the -.Ic my -definition didn't exist prior to perl5. -.Pp -In most cases globals should be defined at the top of the code -using a -.Xr vars 3 -definition block: -.Bd -literal -use vars qw($globalscalar @globalarray %globalhash); -.Ed -.Pp -In some cases it may be appropriate to use -.Ic my -statements at the top of the script as an alternative to using -.Xr vars 3 -declarations. -.Pp -All variables should be commented. -.Bd -literal -sub foo($@) { - my $cmd = shift; # Command to run - my @args = @_; # Arguments to $cmd -} -.Ed -.Pp -Local variables should be separated from function arguments by a -blank line: -.Bd -literal -sub foo($@) { - my $cmd = shift; # Command to run - my @args = @_; # Arguments to command - - my $pid; # Child PID - local *PIPE; # Pipe - my $output; # Output from command -} -.Ed -.Pp -Whenever possible code should be run through the code checker -.Nm perl -.Fl wc -.Ar script.pl -or -.Nm perl -.Fl wcT -.Ar script.pl -and produce no warnings. -.Pp -Indentation is an 8 character tab. -Second level indents are four spaces. -.Bd -literal -while (cnt < 20) { - z = a + really + long + statement + that + needs + - two lines + gets + indented + four + spaces + - on + the + second + and + subsequent + lines. -} -.Ed -.Pp -Do not add whitespace at the end of a line, and only use tabs -followed by spaces to form the indentation. -Do not use more spaces -than a tab will produce and do not use spaces in front of tabs. -.Pp -Opening braces should be at the end of the controlling line. -Else -and elsif belong on the same line as the closing brace for the -previous if or elsif block: -.Bd -literal -sub foo($@) { - my $cmd = shift; # Command to run - my @args = @_; # Arguments to command - - my $pid; # Child PID - local *PIPE; # Pipe - my $output; # Output from command - - unless (defined($pid = open(PIPE, "-|"))) { - die("open(): $!\\n"); - } elsif ($pid == 0) { - exec($cmd, @args); - die("exec(): $!\\n"); - } - $output = ""; - while (<PIPE>) { - $output .= $_; - } - waitpid($pid, 0); - if ($? & 0xff) { - die("$cmd caught a signal " . ($? & 0x7f) . "\\n"); - } elsif ($?) { - die("$cmd returned exit code " . ($? >> 8) . "\\n"); - } - return $output; -} -.Ed -.Pp -Where possible scripts should use standard modules instead of -rewriting the code inline. -It may be appropriate in some cases to -import a CPAN module into the base system to facilitate this. -.Pp -Use -.Ic chomp -instead of -.Ic chop -where appropriate. -.Pp -Use -.Ic unless -instead of -.Ic if Pq Cm \&! No ...\& -where it improves readability. -.Pp -Where it doesn't conflict with this guide read -.Xr perlstyle 1 -and adopt Larry Wall's style recommendations. -.Sh SEE ALSO -.Xr perlsec 1 , -.Xr perlstyle 1 , -.Xr style 9 -.Sh HISTORY -This man page is largely based on the -.Xr style 9 -man page in -.Fx . |
