[pkgsrc/trunk]: pkgsrc/pkgtools/pkglint/files Reworked the in-file documentat...

[rillig <rillig%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/25665a166ab0
branches:  trunk
changeset: 503458:25665a166ab0
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Sun Nov 20 19:58:46 2005 +0000

description:
Reworked the in-file documentation on pkglint. Added section headings.
Renamed some subroutines to fit into the general scheme.

diffstat:

 pkgtools/pkglint/files/pkglint.pl |  164 ++++++++++++++++++++++++++++++++-----
 1 files changed, 141 insertions(+), 23 deletions(-)

diffs (truncated from 380 to 300 lines):

diff -r e36c2287f8d3 -r 25665a166ab0 pkgtools/pkglint/files/pkglint.pl
--- a/pkgtools/pkglint/files/pkglint.pl Sun Nov 20 19:14:50 2005 +0000
+++ b/pkgtools/pkglint/files/pkglint.pl Sun Nov 20 19:58:46 2005 +0000
@@ -11,7 +11,7 @@
 # Freely redistributable.  Absolutely no warranty.
 #
 # From Id: portlint.pl,v 1.64 1998/02/28 02:34:05 itojun Exp
-# $NetBSD: pkglint.pl,v 1.372 2005/11/20 19:04:20 rillig Exp $
+# $NetBSD: pkglint.pl,v 1.373 2005/11/20 19:58:46 rillig Exp $
 #
 # This version contains lots of changes necessary for NetBSD packages
 # done by:
@@ -30,8 +30,9 @@
 
 package PkgLint::Util;
 #==========================================================================
-# This package is a catch-all for everything that does not fit in any other
-# package. Currently it contains the boolean constants C<false> and C<true>.
+# This package is a catch-all for subroutines that are not application-spe-
+# cific. Currently it contains the boolean constants C<false> and C<true>,
+# as well as a function to print text in a table format.
 #==========================================================================
 BEGIN {
        use Exporter;
@@ -43,6 +44,9 @@
 use constant false     => 0;
 use constant true      => 1;
 
+# Prints the C<$table> on the C<$out> stream. The C<$table> shall be an
+# array of rows, each row shall be an array of cells, and each cell shall
+# be a string.
 sub print_table($$) {
        my ($out, $table) = @_;
        my (@width) = ();
@@ -72,17 +76,19 @@
 
 package PkgLint::Logging;
 #==========================================================================
-# This package provides the subroutines log_error, log_warning and log_info
-# for printing messages to the user in a common format. The three subrou-
-# tines have the parameters $file, $lineno and $message. In case there's no
-# file appropriate for the message, NO_FILE may be passed, likewise for
-# $lineno and NO_LINE_NUMBER. At the end of the program, the subroutine
-# print_summary_and_exit should be called.
+# This package provides subroutines for printing messages to the user in a
+# common format. The subroutines all have the parameters C<$fname>,
+# C<$lineno> and C<$message>. In case there's no appropriate filename for
+# the message, NO_FILE may be passed, likewise for C<$lineno> and
+# NO_LINE_NUMBER. Before printing, the filename is normalized, that is,
+# "/foo/bar/../../" components are removed, as well as "." components.
 #
+At the end of the program, the subroutine
+# print_summary_and_exit should be called. 
 # Examples:
 #   log_error(NO_FILE, NO_LINE_NUMBER, "Invalid command line.");
-#   log_warning($file, NO_LINE_NUMBER, "Not found.");
-#   log_info($file, $lineno, sprintf("invalid character (0x%02x).", $c));
+#   log_warning($fname, NO_LINE_NUMBER, "Not found.");
+#   log_info($fname, $lineno, sprintf("invalid character (0x%02x).", $c));
 #==========================================================================
 
 use strict;
@@ -228,8 +234,22 @@
 
 package PkgLint::FileUtil::Line;
 #==========================================================================
-# A Line is a class that contains the read-only fields C<file>, C<lineno>
-# and C<text>, as well as some methods for printing diagnostics easily.
+# When files are read in by pkglint, they are interpreted in terms of
+# lines. For Makefiles, line continuations are handled properly, allowing
+# multiple physical lines to end in a single logical line. For other files
+# there is a 1:1 translation.
+#
+# A difference between the physical and the logical lines is that the
+# physical lines include the line end sequence, whereas the logical lines
+# do not.
+#
+# A logical line is a class having the read-only fields C<file>,
+# C<lines>, C<text>, C<physlines> and C<is_changed>, as well as some
+# methods for printing diagnostics easily.
+#
+# Some other methods allow modification of the physical lines, but leave
+# the logical line (the C<text>) untouched. These methods are used in the
+# --autofix mode.
 #==========================================================================
 BEGIN {
        import PkgLint::Util qw(
@@ -254,7 +274,7 @@
 sub file($) {
        return shift(@_)->[FILE];
 }
-sub lineno($) {
+sub lines($) {
        return shift(@_)->[LINES];
 }
 sub text($) {
@@ -341,8 +361,12 @@
 
 package PkgLint::FileUtil;
 #==========================================================================
-# This package provides the subroutine load_file, which reads a file
-# completely into memory as an array of lines.
+# This package provides subroutines for loading and saving line-oriented
+# files. The load_file() subroutine loads a file completely into memory,
+# optionally handling continuation line folding. The load_lines() subrou-
+# tine is an abbreviation for the common case of loading files without
+# continuation lines. The save_autofix_lines() subroutine examines an array
+# of lines if some of them have changed. It then saves the modified files.
 #==========================================================================
 use strict;
 use warnings;
@@ -507,6 +531,33 @@
 #== End of PkgLint::FileUtil ==============================================
 
 package main;
+#==========================================================================
+# This package contains the application-specific code of pkglint.
+# Most subroutines in this package follow a strict naming convention:
+#
+# The get_*() functions provide easy access to important non-trivial data
+# structures that are loaded from external files and are therefore cached.
+#
+# The is_*() functions return a boolean value and have no side effects.
+#
+# The checkline_*() procedures check a single line for compliance with some
+# rules.
+#
+# The checklines_*() procedures check an array of lines for compliance.
+# Usually they make use of several checkline_*() procedures.
+#
+# The checkfile_*() procedures load a file and check the lines of that
+# file. Usually they make use of several checklines_*() and checkline_*()
+# procedures.
+#
+# The checkdir_*() procedures check the files of a directory and call
+# checkfile_*() on them.
+#
+# Note: The order of subroutines in the file is mostly historical. One
+# important property is that there are no back-references, that is, if
+# you start reading the code from the top to the bottom you won't find a
+# call to a subroutine you haven't yet seen.
+#==========================================================================
 use strict;
 use warnings;
 
@@ -531,13 +582,18 @@
        );
 }
 
+#
 # Buildtime configuration
+#
+
 use constant conf_rcsidstring  => 'NetBSD';
 use constant conf_distver      => '@DISTVER@';
 use constant conf_make         => '@MAKE@';
 use constant conf_datadir      => '@DATADIR@';
 
+#
 # Command Line Options
+#
 
 my $opt_check_ALTERNATIVES = true;
 my $opt_check_bl3      = true;
@@ -641,13 +697,19 @@
          } ]
 );
 
+#
+# Commonly used regular expressions.
+#
+
 use constant regex_pkgname     => qr"^((?:[\w.+]|-[^\d])+)-(\d(?:\w|\.\d)*)$";
 use constant regex_shellcmd    => qr"^\t(.*)$";
 use constant regex_unresolved  => qr"\$\{";
 use constant regex_validchars  => qr"[\011\040-\176]";
 use constant regex_varassign   => qr"^([-A-Z_a-z0-9.\${}\[]+)\s*(=|\?=|\+=|:=|!=)\s*((?:\\#|[^#])*?)(?:\s*(#.*))?$";
 
-# Global variables
+#
+# Global variables.
+#
 
 my $current_dir;               # The currently checked directory.
 my $is_wip;                    # Is the current directory from pkgsrc-wip?
@@ -667,6 +729,10 @@
                                # to be checked. Mostly relevant with
                                # --recursive.
 
+#
+# Command line parsing and handling.
+#
+
 sub help($$$) {
        my ($out, $exitval, $show_all) = @_;
        my ($prog) = (basename($0));
@@ -752,6 +818,10 @@
        }
 }
 
+#
+# Loading pkglint-specific data from files, part 1.
+#
+
 sub load_make_vars_typemap() {
        my ($vartypes);
        my ($fname);
@@ -867,6 +937,10 @@
        return $load_dist_sites_names;
 }
 
+#
+# Miscellaneous functions
+#
+
 sub is_committed($) {
        my ($fname) = @_;
        my ($basename, $entries);
@@ -997,7 +1071,7 @@
 }
 
 #
-# Subroutines to check an array of lines.
+# Procedures to check an array of lines, part 1.
 #
 
 sub checklines_trailing_empty_lines($) {
@@ -1014,7 +1088,7 @@
 }
 
 #
-# Subroutines to check a file.
+# Procedures to check a file, part 1.
 #
 
 sub checkfile_DESCR($) {
@@ -1247,6 +1321,10 @@
        checkperms($fname);
 }
 
+#
+# Procedures to check an array of lines, part 2.
+#
+
 sub checklines_multiple_patches($) {
        my ($lines) = @_;
        my ($files_in_patch, $patch_state, $line_type, $dellines);
@@ -1308,6 +1386,10 @@
        }
 }
 
+#
+# Procedures to check a file, part 2.
+#
+
 sub checkfile_patches_patch($) {
        my ($fname) = @_;
        my ($lines);
@@ -1336,6 +1418,10 @@
        checklines_multiple_patches($lines);
 }
 
+#
+# Loading package-specific data from files.
+#
+
 sub readmakefile($$$$);
 sub readmakefile($$$$) {
        my ($file, $main_lines, $all_lines, $seen_Makefile_include) = @_;
@@ -1420,6 +1506,10 @@
        return $contents;
 }
 
+#
+# Loading data from pkglint-specific files, part 2.
+#
+
 # The pkglint author thinks that variables containing lists of things
 # should have a name indicating some plural form. Sadly, there are other
 # reasons like backwards compatibility and other developer's
@@ -1537,7 +1627,11 @@
        return $get_tool_names_value;
 }
 
-sub checktext_basic_vartype($$$$$) {
+#
+# Procedures to check a single line, part 3.
+#
+
+sub checkline_basic_vartype($$$$$) {
        my ($line, $varname, $type, $value, $comment) = @_;
        my ($value_novar);
 
@@ -1849,16 +1943,20 @@
 
                        if (defined($element_type)) {
                                foreach my $v (@values) {
-                                       checktext_basic_vartype($line, $varname, $element_type, $v, $comment);
+                                       checkline_basic_vartype($line, $varname, $element_type, $v, $comment);
                                }