[SCM] Debian package checker branch, master, updated. 2.0.0-13-g0094324
The following commit has been merged in the master branch:
commit 17b08d0ce2de512119507243f03d682c3041e356
Author: Frank Lichtenheld <djpig@debian.org>
Date: Tue Sep 23 16:12:39 2008 +0200
Lintian::Output: Add POD documentation
Reorder the code to fit better with the structure of the documentation.
diff --git a/lib/Lintian/Output.pm b/lib/Lintian/Output.pm
index 3fc41aa..8547ff6 100644
--- a/lib/Lintian/Output.pm
+++ b/lib/Lintian/Output.pm
@@ -1,4 +1,4 @@
-# Copyright (C) 2008 Frank Lichtenheld <frank@lichtenheld.de>
+# Copyright © 2008 Frank Lichtenheld <frank@lichtenheld.de>
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
@@ -23,10 +23,85 @@ use warnings;
use v5.8.0; # for PerlIO
+=head1 NAME
+
+Lintian::Output - Lintian messaging handling
+
+=head1 SYNOPSIS
+
+ # non-OO
+ use Lintian::Output qw(:messages)
+
+ $Lintian::Output::GLOBAL->verbose(1);
+
+ msg("Something interesting");
+ v_msg("Something less interesting");
+ debug_msg(3, "Something very specfific");
+
+ # OO
+ use Lintian::Output;
+
+ my $out = new Lintian::Output;
+
+ $out->quiet(1);
+ $out->msg("Something interesting");
+ $out->v_msg("Something less interesting");
+ $out->debug_msg(3, "Something very specfific");
+
+=head1 DESCRIPTION
+
+Lintian::Output is used for all interaction between lintian and the user.
+It is designed to be easily extendable via subclassing.
+
+To simplify usage in the most common cases, many Lintian::Output methods
+can be used as class methods and will therefor automatically use the object
+$Lintian::Output::GLOBAL unless their first argument C<isa('Lintian::Output')>.
+
+=cut
+
# support for ANSI color output via colored()
use Term::ANSIColor ();
use Tags ();
+=head1 ACCESSORS
+
+The following fields define the behaviours of Lintian::Output.
+
+=over 4
+
+=item quiet
+
+If true, will suppress all messages except for warnings.
+
+=item verbose
+
+If true, will enable messages issued with v_msg.
+
+=item debug
+
+If set to a positive integer, will enable all debug messages issued with
+a level lower or equal to its value.
+
+=item color
+
+Can take the values "never", "always", or "auto".
+
+Whether to colorize tags based on their severity. The default is "never",
+which never uses color. "always" will always use color, "auto" will use
+color only if the output is going to a terminal,
+
+=item stdout
+
+I/O handle to use for output of messages and tags. Defaults to C<\*STDOUT>.
+
+=item stderr
+
+I/O handle to use for warnings. Defaults to C<\*STDERR>.
+
+=back
+
+=cut
+
use base qw(Class::Accessor Exporter);
Lintian::Output->mk_accessors(qw(verbose debug quiet color colors stdout stderr));
@@ -55,19 +130,38 @@ sub new {
return $self;
}
-sub debug_msg {
- my ($self, $level, @args) = _global_or_object(@_);
+=head1 CLASS/INSTANCE METHODS
- return unless $self->debug && ($self->debug >= $level);
+These methods can be used both with and without an object. If no object
+is given, they will fall back to the $Lintian::Output::GLOBAL object.
- $self->_message(@args);
-}
+=over 4
-sub warning {
+=item C<msg(@args)>
+
+Will output the strings given in @args, one per line, each line prefixed
+with 'N: '. Will do nothing if quiet is true.
+
+=item C<v_msg(@args)>
+
+Will output the strings given in @args, one per line, each line prefixed
+with 'N: '. Will do nothing unless verbose is true.
+
+=item C<debug_msg($level, @args)>
+
+$level should be a positive integer.
+
+Will output the strings given in @args, one per line, each line prefixed
+with 'N: '. Will do nothing unless debug is set to a positive integer
+>= $level.
+
+=cut
+
+sub msg {
my ($self, @args) = _global_or_object(@_);
return if $self->quiet;
- $self->_warning(@args);
+ $self->_message(@args);
}
sub v_msg {
@@ -77,28 +171,52 @@ sub v_msg {
$self->_message(@args);
}
-sub msg {
+sub debug_msg {
+ my ($self, $level, @args) = _global_or_object(@_);
+
+ return unless $self->debug && ($self->debug >= $level);
+
+ $self->_message(@args);
+}
+
+=item C<warning(@args)>
+
+Will output the strings given in @args on stderr, one per line, each line
+prefixed with 'warning: '.
+
+=cut
+
+sub warning {
my ($self, @args) = _global_or_object(@_);
return if $self->quiet;
- $self->_message(@args);
+ $self->_warning(@args);
}
-sub string {
- my ($self, $lead, @args) = _global_or_object(@_);
+=item C<delimiter()>
- my $output = '';
- if (@args) {
- foreach (@args) {
- $output .= $lead.': '.$_."\n";
- }
- } elsif ($lead) {
- $output .= $lead.".\n";
- }
+Gives back a string that is usable for separating messages in the output.
+Note: This does not print anything, it just gives back the string, use
+with one of the methods above, e.g.
- return $output;
+ v_msg('foo', delimiter(), 'bar');
+
+=cut
+
+sub delimiter {
+ my ($self) = _global_or_object(@_);
+
+ return $self->_delimiter;
}
+=item C<print_tag($pkg_info, $tag_info, $extra)>
+
+Print a tag. The first two arguments are hash reference with the information
+about the package and the tag, $extra is the extra information for the tag
+(if any) as an array reference. Tags::tag() is a wrapper around this.
+
+=cut
+
sub print_tag {
my ( $self, $pkg_info, $tag_info, $information ) = _global_or_object(@_);
@@ -122,36 +240,82 @@ sub print_tag {
$self->_print('', "$code: $pkg_info->{pkg}$type", "$tag$extra");
}
-sub _do_color {
- my ($self) = @_;
+=item C<string($lead, @args)>
- return ($self->color eq 'always'
- || ($self->color eq 'auto'
- && -t $self->stdout));
-}
+TODO: Is the part of the public interface?
-sub delimiter {
- my ($self) = _global_or_object(@_);
+=cut
- return $self->_delimiter;
-}
+sub string {
+ my ($self, $lead, @args) = _global_or_object(@_);
-sub _delimiter {
- return '----';
+ my $output = '';
+ if (@args) {
+ foreach (@args) {
+ $output .= $lead.': '.$_."\n";
+ }
+ } elsif ($lead) {
+ $output .= $lead.".\n";
+ }
+
+ return $output;
}
+=back
+
+=head1 INSTANCE METHODS (for subclassing)
+
+The following methods are only intended for subclassing and are
+only available as instance methods. The methods mentioned above
+usually only check whether they should do anything at all (according
+to the values of quiet, verbose, and debug) and then call one of
+the following methods to do the actual printing. Allmost all of them
+finally call _print() to do that. This convoluted scheme is necessary
+to be able to use the methods above as class methods and still make
+the behaviour overridable in subclasses.
+
+=over 4
+
+=item C<_message(@args)>
+
+Called by msg(), v_msg(), and debug_msg() to print the
+message.
+
+=cut
+
sub _message {
my ($self, @args) = @_;
$self->_print('', 'N', @args);
}
+=item C<_warning(@args)>
+
+Called by warning() to print the warning.
+
+=cut
+
sub _warning {
my ($self, @args) = @_;
$self->_print($self->stderr, 'warning', @args);
}
+=item C<_print($stream, $lead, @args)>
+
+Called by _message(), _warning(), and print_tag() to do
+the actual printing.
+
+If you override these three methods, you can change
+the calling convention for this method to pretty much
+whatever you want.
+
+The version in Lintian::Output prints the strings in
+@args, one per line, each line preceded by $lead to
+the I/O handle given in $stream.
+
+=cut
+
sub _print {
my ($self, $stream, $lead, @args) = @_;
$stream ||= $self->stdout;
@@ -160,6 +324,46 @@ sub _print {
print {$stream} $output;
}
+=item C<_delimiter()>
+
+Called by delimiter().
+
+=cut
+
+sub _delimiter {
+ return '----';
+}
+
+=item C<_do_color()>
+
+Called by print_tag() to determine whether to produce colored
+output.
+
+=cut
+
+sub _do_color {
+ my ($self) = @_;
+
+ return ($self->color eq 'always'
+ || ($self->color eq 'auto'
+ && -t $self->stdout));
+}
+
+=back
+
+=head1 CLASS METHODS
+
+=over 4
+
+=item C<_global_or_object(@args)>
+
+If $args[0] is a object which satisfies C<isa('Lintian::Output')>
+returns @args, otherwise returns C<($Lintian::Output::GLOBAL, @_)>.
+
+=back
+
+=cut
+
sub _global_or_object {
if (ref($_[0]) and $_[0]->isa('Lintian::Output')) {
return @_;
@@ -169,3 +373,31 @@ sub _global_or_object {
}
1;
+__END__
+
+=head1 EXPORTS
+
+Lintian::Output exports nothing by default, but the following export
+tags are available:
+
+=over 4
+
+=item :messages
+
+Exports all the methods in L<CLASS/INSTANCE METHODS>
+
+=item :util
+
+Exports all the methods in L<CLASS METHODS>
+
+=back
+
+=head1 AUTHOR
+
+Originally written by Frank Lichtenheld <djpig@debian.org> for Lintian.
+
+=head1 SEE ALSO
+
+lintian(1)
+
+=cut
--
Debian package checker
Reply to: