adding example script and test for it, and fixing POD according to warnings from POD::Checker

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

7 files changed, 275 insertions, 7 deletions

diff --git a/MANIFEST b/MANIFEST
index bbee644..61f396b 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -2,6 +2,8 @@ Changes
 Makefile.PL
 MANIFEST
 README
+t/check_stuff.pl
+t/check_stuff.t
 t/Nagios-Plugin.t
 t/Nagios-Plugin-Performance.t
 t/Nagios-Plugin-Range.t
diff --git a/lib/Nagios/Plugin.pm b/lib/Nagios/Plugin.pm
index c14dfa6..0915571 100644
--- a/lib/Nagios/Plugin.pm
+++ b/lib/Nagios/Plugin.pm
@@ -86,6 +86,12 @@ This is the place for common routines when writing Nagios plugins. The idea is t
 easy as possible for developers to conform to the plugin guidelines 
 (http://nagiosplug.sourceforge.net/developer-guidelines.html).
 
+=head1 EXAMPLE SCRIPT
+
+"Enough talk!  Show me where to start!"
+
+See the file 'check_stuff.pl' in the 't' directory for a complete working example of a plugin script.
+
 =head1 DESIGN
 
 To facilitate object oriented classes, there are multiple perl modules, each reflecting a type of data
@@ -105,22 +111,30 @@ Only methods listed in the documentation for each module is public.
 These modules are experimental and so the interfaces may change up until Nagios::Plugin
 hits version 1.0, but every attempt will be made to make backwards compatible.
 
-=over 4
-
 =head1 STARTING
 
+=over 4
+
 =item use Nagios::Plugin qw(%ERRORS)
 
 Imports the %ERRORS hash. This is currently the only symbol that can be imported.
 
+=back
+
 =head1 CLASS METHODS
 
+=over 4
+
 =item Nagios::Plugin->new( shortname => $$ )
 
 Initializes a new Nagios::Plugin object. Can specify the shortname here.
 
+=back
+
 =head1 OBJECT METHODS
 
+=over 4
+
 =item set_thresholds( warning => "10:25", critical => "~:25" )
 
 Sets the thresholds, based on the range specification at 
@@ -147,9 +161,13 @@ http://nagiosplug.sourceforge.net
 
 =head1 AUTHOR
 
-Ton Voon, E<lt>ton.voon@altinity.comE<gt>
+Maintained by the Nagios Plugin development team - http://nagiosplug.sourceforge.net
+
+Originally by Ton Voon, E<lt>ton.voon@altinity.comE<gt>
+
+Nathan Vonnahme added extra tests and subsequent fixes.
 
-Thanks to Nathan Vonnahme for loads of extra tests and subsequent fixes.
+Gavin Carr contributed the Nagios::Plugin::GetOpt module.
 
 =head1 COPYRIGHT AND LICENSE
 
diff --git a/lib/Nagios/Plugin/Getopt.pm b/lib/Nagios/Plugin/Getopt.pm
index 1903e8c..d38dced 100644
--- a/lib/Nagios/Plugin/Getopt.pm
+++ b/lib/Nagios/Plugin/Getopt.pm
@@ -296,9 +296,7 @@ __END__
 
 =head1 NAME
 
-Nagios::Plugin::Getopt - OO perl module providing standardised argument 
-processing for Nagios plugins
-
+Nagios::Plugin::Getopt - OO perl module providing standardised argument processing for Nagios plugins
 
 =head1 VERSION
 
diff --git a/lib/Nagios/Plugin/Performance.pm b/lib/Nagios/Plugin/Performance.pm
index 83c92fb..9e99f54 100644
--- a/lib/Nagios/Plugin/Performance.pm
+++ b/lib/Nagios/Plugin/Performance.pm
@@ -106,8 +106,12 @@ Once the performance string has been parsed, you can query the label, value, uom
 Returns an array of Nagios::Plugin::Performance objects based on the string entered. 
 If there is an error parsing the string, an empty array is returned.
 
+=back
+
 =head1 OBJECT METHODS
 
+=over 4
+
 =item label, value, uom, min, max
 
 These all return scalars. min and max are not well supported yet.
diff --git a/lib/Nagios/Plugin/Threshold.pm b/lib/Nagios/Plugin/Threshold.pm
index f3410e8..9e7b938 100644
--- a/lib/Nagios/Plugin/Threshold.pm
+++ b/lib/Nagios/Plugin/Threshold.pm
@@ -83,6 +83,8 @@ Returns the warning or critical range as a Nagios::Plugin::Range object.
 
 Given a value, will see if the value breeches the critical or the warning range. Returns the status code.
 
+=back
+
 =head1 AUTHOR
 
 Ton Voon, E<lt>ton.voon@altinity.comE<gt>
diff --git a/t/check_stuff.pl b/t/check_stuff.pl
new file mode 100755
index 0000000..51f551f
--- /dev/null
+++ b/t/check_stuff.pl
@@ -0,0 +1,168 @@
+#!/usr/local/bin/perl
+
+###  check_stuff.pl
+
+# an example Nagios plugin using the Nagios::Plugin modules.  
+
+# Originally by Nathan Vonnahme, n8v at users dot sourceforge
+# dot net, July 19 2006
+
+# Please modify to your heart's content and use as the basis for all
+# the really cool Nagios monitoring scripts you're going to create.
+# You rock.  
+
+# $Id$
+
+##############################################################################
+# prologue
+use strict;
+use warnings;
+
+use Nagios::Plugin qw(%ERRORS);
+
+use Nagios::Plugin::Getopt;
+
+
+use vars qw($VERSION $PROGNAME  $verbose $warn $critical $timeout $result);
+'$Revision$' =~ /^.*(\d+.\d+) \$$/;  # Use The Revision from RCS/CVS/Subversion
+$VERSION = $1;
+$0 =~ m!^.*/([^/]+)$!;
+$PROGNAME = $1;
+
+# shortname is the identifier this script will give to Nagios.  
+# it's set here to the uppercase program name with file extension removed,
+#  e.g.   check_stuff.pl  ->  CHECK_STUFF
+my $short_name = uc $PROGNAME;
+$short_name =~ s/\.\w+$//;
+
+
+##############################################################################
+# define and get the command line options.
+#   see the command line option guidelines at 
+#   
+
+
+# Instantiate Nagios::Plugin::Getopt object (usage and version are mandatory)
+my $nagopts = Nagios::Plugin::Getopt->new(
+    usage => "Usage: %s [ -v|--verbose ]  [-H <host>] [-t <timeout>]
+    [ -c|--critical=<critical threshold> ] 
+    [ -w|--warning=<warning threshold> ]  
+    [ -r|--result = <INTEGER> ]",
+    version => $VERSION,
+    blurb => 'This plugin is an example of a Nagios plugin written in Perl using the Nagios::Plugin modules.  It will generate a random integer between 1 and 20 (though you can specify the number with the -n option for testing), and will output OK, WARNING or CRITICAL if the resulting number is outside the specified thresholds.', 
+
+        extra => qq{
+
+THRESHOLDs for -w and -c are specified 'min:max' or 'min:' or ':max'
+(or 'max'). If specified '\@min:max', a warning status will be generated
+if the count *is* inside the specified range.
+
+See more threshold examples at
+  http://nagiosplug.sourceforge.net/developer-guidelines.html#THRESHOLDFORMAT
+
+Examples:
+
+ $PROGNAME -w 10 -c 18
+    Returns a warning if the resulting number is greater than 10, or a
+    critical error if it is greater than 18.
+
+ $PROGNAME -w 10: -c 4:
+        Returns a warning if the resulting number is less than 10, or a
+        critical error if it is less than 4.
+
+
+}
+
+);
+
+
+# Define and document the valid command line options
+# usage, help, version, timeout and verbose are defined by default.
+
+$nagopts->arg(
+        spec => 'warning|w=s',
+
+        help => 
+qq{-w, --warning=INTEGER:INTEGER
+   Minimum and maximum number of allowable result, outside of which a
+   warning will be generated.  If omitted, no warning is generated.},
+
+#       required => 1,
+#       default => 10,
+);
+
+$nagopts->arg(
+        spec => 'critical|c=s',
+        help => 
+qq{-c, --critical=INTEGER:INTEGER
+   Minimum and maximum number of the generated result, outside of
+   which a critical will be generated. If omitted, a critical is
+   generated if no processes are running.},
+
+);
+
+$nagopts->arg(
+        spec => 'result|r=f',
+        help => 
+qq{-r, --result=INTEGER
+   Specify the result on the command line rather than generating a
+   random number.  For testing.},
+);
+
+# Parse arguments and process standard ones (e.g. usage, help, version)
+$nagopts->getopts;
+
+
+my $p = Nagios::Plugin->new;
+
+$p->shortname($short_name);
+
+
+# sanity checking on command line options
+if ( (defined $nagopts->result) && ($nagopts->result < 0 || $nagopts->result > 20) )  {
+    $p->die( 
+                return_code => $ERRORS{UNKNOWN}, 
+                message => 'invalid number supplied for the -r option'
+             );
+}
+
+unless ( defined $nagopts->warning || defined $nagopts->critical ) {
+        $p->die( 
+                         return_code => $ERRORS{UNKNOWN}, 
+                         message => "you didn't supply a threshold argument" 
+                         );
+}
+
+##############################################################################
+# define a Nagios::Threshold object based on the command line options
+my $t = $p->set_thresholds( warning => $nagopts->warning, critical => $nagopts->critical );
+
+
+##############################################################################
+# check stuff.
+
+# THIS is where you'd do your actual checking to get a real value for $result
+#  don't forget to timeout after $nagopts->timeout seconds, if applicable.
+my $result;
+if (defined $nagopts->result) {
+    $result = $nagopts->result;
+    print "using supplied result $result from command line\n" if $nagopts->verbose;
+}
+else {
+    $result = int rand(20)+1;
+    print "generated random result $result\n" if $nagopts->verbose;
+}
+
+print "status of result ($result) is ", $t->get_status($result), "\n"  
+    if $nagopts->verbose;
+
+
+
+
+##############################################################################
+# output the result and exit
+$p->die( 
+         return_code => $t->get_status($result), 
+         message => "sample result was $result" 
+);
+
diff --git a/t/check_stuff.t b/t/check_stuff.t
new file mode 100755
index 0000000..a748605
--- /dev/null
+++ b/t/check_stuff.t
@@ -0,0 +1,76 @@
+#!/usr/local/bin/perl
+# 
+use strict; use warnings;
+#use Test::More qw(no_plan);
+use Test::More tests => 16;
+
+my ($r,$args);
+my $s = 't/check_stuff.pl';
+$s = 'perl -Ilib '.$s;
+
+my $n = 'CHECK_STUFF';
+
+# Nagios status strings and exit codes
+my %e  = qw(
+                         OK           0
+                         WARNING      1
+                         CRITICAL     2
+                         UNKNOWN      3
+                         );
+
+$r = `$s`;
+is      $?>>8 ,         $e{UNKNOWN},            "exits($e{UNKNOWN}) with no args";
+like    $r,             qr/^$n UNKNOWN/,        "UNKNOWN with no args";
+
+
+#TODO:
+SKIP: {
+        local $TODO = q~d'oh! we'll have to redirect STDERR and check it with like() here instead of checking `` which only gets STDIN.  Maybe use IPC::Open3?~;
+        skip "too noisy, see TODO here", 6;
+
+        $r = `$s -V`;
+        is      $?>>8 ,         $e{UNKNOWN},            "exits($e{UNKNOWN}) with -V arg";
+        like    $r,             qr/\d+\.\d/i,   "looks like there's a version";  # broken
+        is $r, '', "prints nothing to STDOUT";
+
+        $r = `$s -h`;
+        is      $?>>8 ,         $e{UNKNOWN},            "exits($e{UNKNOWN}) with -h arg";
+        like    $r,             qr/usage/i,     "looks like there's something helpful";  # broken
+        is $r, '', "prints nothing to STDOUT";
+}
+
+
+$args = " -r 99 ";
+diag "running `$s $args`" if $ENV{TEST_VERBOSE};
+$r = `$s $args`;
+diag "output:  '$r'" if $ENV{TEST_VERBOSE};
+is      $?>>8 ,         $e{UNKNOWN},            "exits($e{UNKNOWN}) with $args";
+like    $r,             qr/UNKNOWN.+invalid/i,  "UNKNOWN (warning: invalid -r) with $args";
+
+
+my $expected = {
+        " -w 10:15 -c~:15 -r 0"     =>  'WARNING',
+        " -w 10:15 -c~:15 -r 11"     =>  'OK',
+        " -w 10:15 -c~:15 -r 15.8"   =>  'CRITICAL',
+};
+
+test_expected( $s, $expected );
+
+
+sub test_expected {
+        my $s = shift;
+    my $expected = shift;
+    foreach ( keys %$expected ) {
+                diag "running `$s $_`" if $ENV{TEST_VERBOSE};
+                $r = `$s $_`;
+                diag "output:  '$r'" if $ENV{TEST_VERBOSE};
+                is      $?>>8 ,         $e{$expected->{$_}},            "exits($e{$expected->{$_}}) with $_";
+                like    $r,             qr/^$n $expected->{$_}/i,       "looks $expected->{$_} with $_";
+        }
+}
+
+
+
+
+
+