Rename NP::Base to NP::Functions; add check_messages() to NP::Functions.

git-svn-id: https://nagiosplug.svn.sourceforge.net/svnroot/nagiosplug/Nagios-Plugin/trunk@1482 f882894a-f735-0410-b71e-b25c423dba1c

8 files changed, 359 insertions, 211 deletions

diff --git a/lib/Nagios/Plugin.pm b/lib/Nagios/Plugin.pm
index 41bff91..5ff6709 100644
--- a/lib/Nagios/Plugin.pm
+++ b/lib/Nagios/Plugin.pm
@@ -11,7 +11,7 @@ struct "Nagios::__::Plugin" => {
 
 package Nagios::Plugin;
 
-use Nagios::Plugin::Base;
+use Nagios::Plugin::Functions;
 use Nagios::Plugin::Performance;
 use Nagios::Plugin::Threshold;
 
@@ -24,7 +24,7 @@ use Exporter;
 our @ISA = qw(Exporter Nagios::__::Plugin);
 our @EXPORT_OK = qw(%ERRORS);
 
-our $VERSION = $Nagios::Plugin::Base::VERSION;
+our $VERSION = $Nagios::Plugin::Functions::VERSION;
 
 sub add_perfdata {
         my ($self, %args) = @_;
@@ -41,7 +41,7 @@ sub set_thresholds { shift; Nagios::Plugin::Threshold->set_thresholds(@_); }
 
 sub die {
         my $self = shift;
-        Nagios::Plugin::Base::die(@_, { plugin => $self });
+        Nagios::Plugin::Functions::die(@_, { plugin => $self });
 }
 
 1;
diff --git a/lib/Nagios/Plugin/Base.pm b/lib/Nagios/Plugin/Base.pm
deleted file mode 100644
index 92651ed..0000000
--- a/lib/Nagios/Plugin/Base.pm
+++ /dev/null
@@ -1,196 +0,0 @@
-# This module holds all exported variables
-# and base functions
-package Nagios::Plugin::Base;
-
-use strict;
-use warnings;
-use File::Basename;
-
-our $VERSION = "0.13";
-
-our @STATUS_CODES = qw(OK WARNING CRITICAL UNKNOWN DEPENDENT);
-
-require Exporter;
-our @ISA = qw(Exporter);
-our @EXPORT = (@STATUS_CODES, qw(nagios_exit %ERRORS));
-our @EXPORT_OK = qw(nagios_die %STATUS_TEXT);
-our %EXPORT_TAGS = (
-    all => [ @EXPORT, @EXPORT_OK ],
-    codes => [ @STATUS_CODES ],
-    functions => [ qw(nagios_exit nagios_die) ],
-);
-
-use constant OK         => 0;
-use constant WARNING    => 1;
-use constant CRITICAL   => 2;
-use constant UNKNOWN    => 3;
-use constant DEPENDENT  => 4;
-
-our %ERRORS = (
-    'OK' => OK,
-    'WARNING'   => WARNING,
-    'CRITICAL'  => CRITICAL,
-    'UNKNOWN'   => UNKNOWN,
-    'DEPENDENT' => DEPENDENT,
-);
-
-our %STATUS_TEXT = reverse %ERRORS;
-
-# _fake_exit flag and accessor/mutator, for testing
-my $_fake_exit = 0;
-sub _fake_exit { @_ ? $_fake_exit = shift : $_fake_exit };
-
-sub get_shortname {
-    my %arg = @_;
-
-    return $arg{plugin}->shortname if $arg{plugin};
-
-    my $shortname = uc basename($ENV{NAGIOS_PLUGIN} || $0);
-    $shortname =~ s/^CHECK_//;
-    return $shortname;
-}
-
-# nagios_exit( $code, $message )
-sub nagios_exit {
-    my ($code, $message, $arg) = @_;
-
-    # Handle named parameters
-    if (defined $code && ($code eq 'return_code' || $code eq 'message')) {
-        # Remove last argument if odd no and last is ref
-        if (int(@_ / 2) != @_ / 2 && ref $_[$#_]) {
-            $arg = pop @_;
-        } else {
-            undef $arg;
-        }
-        my %arg = @_;
-        $code = $arg{return_code};
-        $message = $arg{message};
-    }
-    $arg ||= {};
-
-    # Handle string codes
-    $code = $ERRORS{$code} if defined $code && exists $ERRORS{$code};
-
-    # Set defaults
-    $code = UNKNOWN unless defined $code && exists $STATUS_TEXT{$code};
-    $message = '' unless defined $message;
-    $message = join(' ', @$message) if ref $message eq 'ARRAY';
-
-    # Setup output
-    my $output = "$STATUS_TEXT{$code}";
-    $output .= " - $message" if defined $message && $message ne '';
-    my $shortname = get_shortname(plugin => $arg->{plugin});
-    $output = "$shortname $output" if $shortname;
-    if ($arg->{plugin}) {
-        my $plugin = $arg->{plugin};
-        $output .= " | ". $plugin->all_perfoutput if $plugin->perfdata;
-    }
-    $output .= "\n";
-
-    # Don't actually exit if _fake_exit set
-    if ($_fake_exit) {
-        require Nagios::Plugin::ExitResult;
-        return Nagios::Plugin::ExitResult->new($code, $output);
-    }
-
-    # Print output and exit
-    print $output;
-    exit $code;
-}
-
-# nagios_die( $message, [ $code ])   OR   nagios_die( $code, $message )
-# Default $code: UNKNOWN
-sub nagios_die {
-    my ($arg1, $arg2, $rest) = @_;
-
-    # Named parameters
-    if (defined $arg1 && ($arg1 eq 'return_code' || $arg1 eq 'message')) {
-        return nagios_exit(@_);
-    }
-
-    # ($code, $message)
-    elsif (defined $arg1 && (exists $ERRORS{$arg1} || exists $STATUS_TEXT{$arg1})) {
-        return nagios_exit(@_);
-    }
-
-    # ($message, $code)
-    elsif (defined $arg2 && (exists $ERRORS{$arg2} || exists $STATUS_TEXT{$arg2})) {
-        return nagios_exit($arg2, $arg1, $rest);
-    }
-
-    # Else just assume $arg1 is the message and hope for the best
-    else {
-        return nagios_exit( UNKNOWN, $arg1, $rest );
-    }
-}
-
-# For backwards compatibility
-sub die { nagios_die(@_); }
-
-
-=pod old
-
-my $exit_on_die = 1;
-sub exit_on_die { shift; @_ ? $exit_on_die = shift : $exit_on_die };
-my $print_on_die = 1;
-sub print_on_die { shift; @_ ? $print_on_die = shift : $print_on_die };
-
-# Old version - TODO: remove
-sub old_die {
-    my ($class, $args, $plugin) = @_;
-    my $return_code;
-
-    if (  exists $args->{return_code} 
-          && exists $STATUS_TEXT{$args->{return_code}}  
-        ) {
-        $return_code = $args->{return_code};
-    }
-    else {
-        $return_code = $ERRORS{UNKNOWN};
-    }
-    my $message = $args->{message} || "Internal error";
-    my $output = join(" ", $STATUS_TEXT{$return_code}, $message);
-    if ($plugin) {
-        $output = $plugin->shortname." $output" if $plugin->shortname;
-        $output .= " | ".$plugin->all_perfoutput if $plugin->perfdata;
-    }
-    if ($print_on_die) {
-        print $output, $/;
-    }
-    if ($exit_on_die) {
-        exit $return_code;
-    } else {
-        return $output;
-    }
-}
-
-=cut
-
-1;
-
-# vim:sw=4:sm:et
-
-__END__
-
-=head1 NAME
-
-Nagios::Plugin::Base - Base functions for Nagios::Plugins
-
-=head1 DESCRIPTION
-
-See Nagios::Plugin for public interfaces. This module is for Nagios::Plugin developers to incorporate
-common backend functionality.
-
-=head1 AUTHOR
-
-Ton Voon, E<lt>ton.voon@altinity.comE<gt>
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright (C) 2006 by Nagios Plugin Development Team
-
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself, either Perl version 5.8.4 or,
-at your option, any later version of Perl 5 you may have available.
-
-=cut
diff --git a/lib/Nagios/Plugin/ExitResult.pm b/lib/Nagios/Plugin/ExitResult.pm
index f059424..191c92a 100644
--- a/lib/Nagios/Plugin/ExitResult.pm
+++ b/lib/Nagios/Plugin/ExitResult.pm
@@ -30,10 +30,10 @@ return codes when testing.
 =head1 SYNOPSIS
 
     use Test::More;
-    use Nagios::Plugin::Base;
+    use Nagios::Plugin::Functions;
 
     # In a test file somewhere
-    Nagios::Plugin::Base::_fake_exit(1);
+    Nagios::Plugin::Functions::_fake_exit(1);
 
     # Later ...
     $e = nagios_exit( CRITICAL, 'aiiii ...' );
@@ -50,7 +50,7 @@ return codes when testing.
 Nagios::Plugin::ExitResult is a tiny helper class intended for use 
 when testing other Nagios::Plugin modules. A Nagios::Plugin::ExitResult 
 object is returned by nagios_exit() and friends when 
-Nagios::Plugin::Base::_fake_exit has been set, instead of doing a 
+Nagios::Plugin::Functions::_fake_exit has been set, instead of doing a 
 conventional print + exit.
 
 =head1 AUTHOR
diff --git a/lib/Nagios/Plugin/Functions.pm b/lib/Nagios/Plugin/Functions.pm
new file mode 100644
index 0000000..9c20288
--- /dev/null
+++ b/lib/Nagios/Plugin/Functions.pm
@@ -0,0 +1,344 @@
+# This module holds all exported variables
+# and base functions
+package Nagios::Plugin::Functions;
+
+use strict;
+use warnings;
+use File::Basename;
+use Params::Validate qw(validate :types);
+
+our $VERSION = "0.13";
+
+our @STATUS_CODES = qw(OK WARNING CRITICAL UNKNOWN DEPENDENT);
+
+require Exporter;
+our @ISA = qw(Exporter);
+our @EXPORT = (@STATUS_CODES, qw(nagios_exit nagios_die check_messages));
+our @EXPORT_OK = qw(%ERRORS %STATUS_TEXT);
+our %EXPORT_TAGS = (
+    all => [ @EXPORT, @EXPORT_OK ],
+    codes => [ @STATUS_CODES ],
+    functions => [ qw(nagios_exit nagios_die check_messages) ],
+);
+
+use constant OK         => 0;
+use constant WARNING    => 1;
+use constant CRITICAL   => 2;
+use constant UNKNOWN    => 3;
+use constant DEPENDENT  => 4;
+
+our %ERRORS = (
+    'OK' => OK,
+    'WARNING'   => WARNING,
+    'CRITICAL'  => CRITICAL,
+    'UNKNOWN'   => UNKNOWN,
+    'DEPENDENT' => DEPENDENT,
+);
+
+our %STATUS_TEXT = reverse %ERRORS;
+
+# _fake_exit flag and accessor/mutator, for testing
+my $_fake_exit = 0;
+sub _fake_exit { @_ ? $_fake_exit = shift : $_fake_exit };
+
+sub get_shortname {
+    my %arg = @_;
+
+    return $arg{plugin}->shortname if $arg{plugin};
+
+    my $shortname = uc basename($ENV{NAGIOS_PLUGIN} || $0);
+    $shortname =~ s/^CHECK_//;
+    return $shortname;
+}
+
+# nagios_exit( $code, $message )
+sub nagios_exit {
+    my ($code, $message, $arg) = @_;
+
+    # Handle named parameters
+    if (defined $code && ($code eq 'return_code' || $code eq 'message')) {
+        # Remove last argument if odd no and last is ref
+        if (int(@_ / 2) != @_ / 2 && ref $_[$#_]) {
+            $arg = pop @_;
+        } else {
+            undef $arg;
+        }
+        my %arg = @_;
+        $code = $arg{return_code};
+        $message = $arg{message};
+    }
+    $arg ||= {};
+
+    # Handle string codes
+    $code = $ERRORS{$code} if defined $code && exists $ERRORS{$code};
+
+    # Set defaults
+    $code = UNKNOWN unless defined $code && exists $STATUS_TEXT{$code};
+    $message = '' unless defined $message;
+    $message = join(' ', @$message) if ref $message eq 'ARRAY';
+
+    # Setup output
+    my $output = "$STATUS_TEXT{$code}";
+    $output .= " - $message" if defined $message && $message ne '';
+    my $shortname = get_shortname(plugin => $arg->{plugin});
+    $output = "$shortname $output" if $shortname;
+    if ($arg->{plugin}) {
+        my $plugin = $arg->{plugin};
+        $output .= " | ". $plugin->all_perfoutput if $plugin->perfdata;
+    }
+    $output .= "\n";
+
+    # Don't actually exit if _fake_exit set
+    if ($_fake_exit) {
+        require Nagios::Plugin::ExitResult;
+        return Nagios::Plugin::ExitResult->new($code, $output);
+    }
+
+    # Print output and exit
+    print $output;
+    exit $code;
+}
+
+# nagios_die( $message, [ $code ])   OR   nagios_die( $code, $message )
+# Default $code: UNKNOWN
+sub nagios_die {
+    my ($arg1, $arg2, $rest) = @_;
+
+    # Named parameters
+    if (defined $arg1 && ($arg1 eq 'return_code' || $arg1 eq 'message')) {
+        return nagios_exit(@_);
+    }
+
+    # ($code, $message)
+    elsif (defined $arg1 && (exists $ERRORS{$arg1} || exists $STATUS_TEXT{$arg1})) {
+        return nagios_exit(@_);
+    }
+
+    # ($message, $code)
+    elsif (defined $arg2 && (exists $ERRORS{$arg2} || exists $STATUS_TEXT{$arg2})) {
+        return nagios_exit($arg2, $arg1, $rest);
+    }
+
+    # Else just assume $arg1 is the message and hope for the best
+    else {
+        return nagios_exit( UNKNOWN, $arg1, $rest );
+    }
+}
+
+# For backwards compatibility
+sub die { nagios_die(@_); }
+
+
+# ------------------------------------------------------------------------
+# check_messages - return a status and/or message based on a set of 
+#   message arrays.
+#   Returns a nagios status code in scalar context. 
+#   Returns a code and a message in list context.
+#   The message is join($join, @array) for the relevant array for the code,
+#     or join($join_all, $message) for all arrays if $join_all is set.
+sub check_messages {
+    my %arg = validate( @_, {
+        critical        => { type => ARRAYREF },
+        warning         => { type => ARRAYREF },
+        ok              => { type => ARRAYREF | SCALAR, optional => 1 },
+        'join'          => { default => ' ' },
+        join_all        => 0,
+    });
+    $arg{join} = ' ' unless defined $arg{join};
+
+    # Decide $code
+    my $code = OK;
+    $code ||= CRITICAL  if @{$arg{critical}};
+    $code ||= WARNING   if @{$arg{warning}};
+    return $code unless wantarray;
+
+    # Compose message
+    my $message = '';
+    if ($arg{join_all}) {
+        $message = join( $arg{join_all}, 
+            map { @$_ ? join( $arg{'join'}, @$_) : () }
+                $arg{critical}, 
+                $arg{warning},
+                $arg{ok} ? (ref $arg{ok} ? $arg{ok} : [ $arg{ok} ]) : []
+        );
+    }
+
+    else {
+        $message ||= join( $arg{'join'}, @{$arg{critical}} ) 
+            if $code == CRITICAL;
+        $message ||= join( $arg{'join'}, @{$arg{warning}} )  
+            if $code == WARNING;
+        $message ||= ref $arg{ok} ? join( $arg{'join'}, @{$arg{ok}} ) : $arg{ok}
+            if $arg{ok};
+    }
+
+    return ($code, $message);
+}
+
+# ------------------------------------------------------------------------
+
+1;
+
+# vim:sw=4:sm:et
+
+__END__
+
+=head1 NAME
+
+Nagios::Plugin::Functions - functions to simplify the creation of 
+Nagios plugins.
+
+=head1 SYNOPSIS
+
+    # Constants OK, WARNING, CRITICAL, and UNKNOWN exported by default
+    use Nagios::Plugin::Functions;
+
+    # nagios_exit( ODE, $message ) - exit with error code CODE,
+    # and message "PLUGIN CODE - $message"
+    nagios_exit( CRITICAL, $critical_error ) if $critical_error;
+    nagios_exit( WARNING, $warning_error )   if $warning_error;
+    nagios_exit( OK, $result );
+
+    # nagios_die( $message, [$CODE] ) - just like nagios_exit(),
+    # but CODE is optional, defaulting to UNKNOWN
+    do_something()
+      or nagios_die("do_something() failed horribly");
+    do_something_critical()
+      or nagios_die("do_something_critical() failed", CRITICAL);
+
+    # check_messages - check a set of message arrays, returning a 
+    # CODE and/or a result message
+    $code = check_messages(critical => \@crit, warning => \@warn);
+    ($code, $message) = check_messages(
+      critical => \@crit, warning => \@warn,
+      ok => \@ok );
+
+
+=head1 DESCRIPTION
+
+This module is part of the Nagios::Plugin family, a set of modules
+for simplifying the creation of Nagios plugins. This module exports
+convenience functions for the class methods provided by 
+Nagios::Plugin. It is intended for those who prefer a simpler 
+functional interface, and who do not need the additional 
+functionality of Nagios::Plugin.
+
+=head2 Exports
+
+Nagios status code constants are exported by default:
+
+    OK
+    WARNING
+    CRITICAL
+    UNKNOWN
+    DEPENDENT
+
+as are the following functions:
+
+    nagios_exit
+    nagios_die
+    check_messages
+
+The following variables are exported only on request:
+
+    %ERRORS
+    %STATUS_TEXT
+
+
+=head2 Functions
+
+The following functions are supported:
+
+=over 4
+
+=item nagios_exit( CODE, $message )
+
+Exit with return code CODE, and a standard nagios message of the
+form "PLUGIN CODE - $message".
+
+=item nagios_die( $message, [CODE] )
+
+Same as nagios_exit(), except that CODE is optional, defaulting
+to UNKNOWN.
+
+=item check_messages( critical => \@crit, warning => \@warn )
+
+Convenience function to check a set of message arrays and return
+an appropriate nagios return code and/or a result message. Returns
+only a return code in scalar context; returns a return code and an
+error message in list context i.e.
+
+    # Scalar context
+    $code = check_messages(critical => \@crit, warning => \@warn);
+    # List context
+    ($code, $msg) = check_messages(critical => \@crit, warning => \@warn);
+
+check_messages() accepts the following named arguments:
+
+=over 4
+
+=item critical => ARRAYREF
+
+An arrayref of critical error messages - check_messages() returns 
+CRITICAL if this arrayref is non-empty. Mandatory.
+
+=item warning => ARRAYREF
+
+An arrayref of warning error messages - check_messages() returns
+WARNING if this arrayref is non-empty ('critical' is checked
+first). Mandatory.
+
+=item ok => ARRAYREF | SCALAR
+
+An arrayref of informational messages (or a single scalar message),
+used in list context if both the 'critical' and 'warning' arrayrefs
+are empty. Optional.
+
+=item join => SCALAR
+
+A string used to join the relevant array to generate the message 
+string returned in list context i.e. if the 'critical' array @crit
+is non-empty, check_messages would return:
+
+    join( $join, @crit )
+
+as the result message. Optional; default: ' ' (space).
+
+=item join_all => SCALAR
+
+By default, only one set of messages are joined and returned in the
+result message i.e. if the result is CRITICAL, only the 'critical'
+messages are included in the result; if WARNING, only the 'warning' 
+messages are included; if OK, the 'ok' messages are included (if
+supplied) i.e. the default is to return an 'errors-only' type 
+message.
+
+If join_all is supplied, however, it will be used as a string to
+join the resultant critical, warning, and ok messages together i.e.
+all messages are joined and returned.
+
+=back
+
+=back
+
+
+=head1 SEE ALSO
+
+Nagios::Plugin; the nagios plugin developer guidelines at
+http://nagiosplug.sourceforge.net/developer-guidelines.html.
+
+
+=head1 AUTHORS
+
+Ton Voon, E<lt>ton.voon@altinity.comE<gt>
+
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright (C) 2006 by Nagios Plugin Development Team
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself, either Perl version 5.8.4 or,
+at your option, any later version of Perl 5 you may have available.
+
+=cut
diff --git a/lib/Nagios/Plugin/Getopt.pm b/lib/Nagios/Plugin/Getopt.pm
index 7f32c3b..8a9fc1c 100644
--- a/lib/Nagios/Plugin/Getopt.pm
+++ b/lib/Nagios/Plugin/Getopt.pm
@@ -12,9 +12,9 @@ use Carp;
 use Params::Validate qw(:all);
 use base qw(Class::Accessor);
 
-use Nagios::Plugin::Base;
+use Nagios::Plugin::Functions;
 use vars qw($VERSION);
-$VERSION = $Nagios::Plugin::Base::VERSION;
+$VERSION = $Nagios::Plugin::Functions::VERSION;
 
 # Standard defaults
 my %DEFAULT = (
@@ -586,7 +586,7 @@ Gavin Carr <gavin@openfusion.com.au>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2005-2006 Gavin Carr. All Rights Reserved.
+Copyright (C) 2006 by the Nagios Plugin Development Team.
 
 This module is free software. It may be used, redistributed
 and/or modified under either the terms of the Perl Artistic 
diff --git a/lib/Nagios/Plugin/Performance.pm b/lib/Nagios/Plugin/Performance.pm
index 9e99f54..38803a6 100644
--- a/lib/Nagios/Plugin/Performance.pm
+++ b/lib/Nagios/Plugin/Performance.pm
@@ -7,8 +7,8 @@ use warnings;
 
 use Carp;
 use Nagios::Plugin::Threshold;
-use Nagios::Plugin::Base;
-our ($VERSION) = $Nagios::Plugin::Base::VERSION;
+use Nagios::Plugin::Functions;
+our ($VERSION) = $Nagios::Plugin::Functions::VERSION;
 
 use Class::Struct;
 struct "Nagios::Plugin::Performance" => {
diff --git a/lib/Nagios/Plugin/Range.pm b/lib/Nagios/Plugin/Range.pm
index b17cc96..f354a54 100644
--- a/lib/Nagios/Plugin/Range.pm
+++ b/lib/Nagios/Plugin/Range.pm
@@ -6,8 +6,8 @@ use strict;
 use warnings;
 use Carp;
 
-use Nagios::Plugin::Base;
-our ($VERSION) = $Nagios::Plugin::Base::VERSION;
+use Nagios::Plugin::Functions;
+our ($VERSION) = $Nagios::Plugin::Functions::VERSION;
 
 use overload
         '""' => sub { shift->stringify };
diff --git a/lib/Nagios/Plugin/Threshold.pm b/lib/Nagios/Plugin/Threshold.pm
index d7a8177..3e14d82 100644
--- a/lib/Nagios/Plugin/Threshold.pm
+++ b/lib/Nagios/Plugin/Threshold.pm
@@ -6,8 +6,8 @@ use strict;
 use warnings;
 
 use Nagios::Plugin::Range;
-use Nagios::Plugin::Base qw(:codes nagios_die);
-our ($VERSION) = $Nagios::Plugin::Base::VERSION;
+use Nagios::Plugin::Functions qw(:codes nagios_die);
+our ($VERSION) = $Nagios::Plugin::Functions::VERSION;
 
 use Class::Struct;
 struct "Nagios::Plugin::Threshold" => {