Moved usage-information to foot of script.

This removes the nasty self-parsing of the script to generate the
help/manual output.  I've also removed global-variables and made
the code almost-100% warning free.

4 files changed, 258 insertions, 368 deletions

diff --git a/bin/custodian-dequeue b/bin/custodian-dequeue
index d49049e..bc84adf 100755
--- a/bin/custodian-dequeue
+++ b/bin/custodian-dequeue
@@ -1,66 +1,20 @@
-#!/usr/bin/ruby -Ilib/ -I../lib/ -rubygems
-#
-# NAME
-#  custodian-dequeue - Pull network tests from a queue and execute them in series.
-#
-# SYNOPSIS
-#  custodian-dequeue  [ -h | --help ]
-#                     [ -m | --manual]
-#                     [ -f | --fail ]
-#                     [ -s | --single ]
-#                     [ -v | --verbose ]
-#
-# OPTIONS
-#
-#  -h, --help          Show a help message, and exit.
-#
-#  -m, --manual        Show this manual, and exit.
-#
-#  -s, --single        Run a single test and exit.
-#
-#  -f, --fail          Stop running once a single test fails.
-#
-#  -v, --verbose       Be noisy.
-#
-#
-# ABOUT
-#
-# This tool is designed to pull network/protocol-tests from the central queue
-# and execute them one by one.
-#
-# The results of the testing will be sent to a notifier, where they can later
-# be acted upon.
+#!/usr/bin/ruby -rubygems
 #
+# Usage information at the end of the script.
 #
-# AUTHOR
-#
-#  Steve Kemp  <steve@bytemark.co.uk>
-#
-
 
-#
-# Standard modules
-#
 require 'getoptlong'
-
-
-#
-# Our code.
-#
 require 'custodian/settings'
 require 'custodian/queue'
 require 'custodian/worker'
 
-
-
-
 #
 #  Entry-point to our code.
 #
-if __FILE__ == $PROGRAM_NAME then
+if __FILE__ == $PROGRAM_NAME
 
-  $help    = false
-  $manual  = false
+  help    = false
+  manual  = false
 
   #
   #  The settings object contains a lot of configuration-data.
@@ -69,24 +23,24 @@ if __FILE__ == $PROGRAM_NAME then
 
   begin
     opts = GetoptLong.new(
-                          ['--help',    '-h', GetoptLong::NO_ARGUMENT],
-                          ['--manual',  '-m', GetoptLong::NO_ARGUMENT],
-                          ['--fail',    '-f', GetoptLong::NO_ARGUMENT],
-                          ['--single',  '-s', GetoptLong::NO_ARGUMENT],
-                          ['--verbose', '-v', GetoptLong::NO_ARGUMENT]
+      ['--help',    '-h', GetoptLong::NO_ARGUMENT],
+      ['--manual',  '-m', GetoptLong::NO_ARGUMENT],
+      ['--fail',    '-f', GetoptLong::NO_ARGUMENT],
+      ['--single',  '-s', GetoptLong::NO_ARGUMENT],
+      ['--verbose', '-v', GetoptLong::NO_ARGUMENT]
                           )
-    opts.each do |opt, arg|
+    opts.each do |opt, _arg|
       case opt
       when '--verbose' then
-          ENV['VERBOSE'] = '1'
+        ENV['VERBOSE'] = '1'
       when '--single' then
-          ENV['SINGLE'] = '1'
+        ENV['SINGLE'] = '1'
       when '--fail' then
-          ENV['FAIL'] = '1'
+        ENV['FAIL'] = '1'
       when '--help' then
-          $help = true
+        help = true
       when '--manual' then
-          $manual = true
+        manual = true
       end
     end
   rescue StandardError => ex
@@ -94,49 +48,26 @@ if __FILE__ == $PROGRAM_NAME then
     exit
   end
 
-
-
   #
-  # CAUTION! Here be quality kode.
+  # Show the help information.
   #
-  if $manual or $help
-
-    # Open the file, stripping the shebang line
-    lines = File.open(__FILE__){|fh| fh.readlines}[1..-1]
-
-    found_synopsis = false
-
-    lines.each do |line|
-
-      line.chomp!
-      break if line.empty?
-
-      if $help and !found_synopsis
-        found_synopsis = (line =~ /^#\s+SYNOPSIS\s*$/)
-        next
-      end
-
-      puts line[2..-1].to_s
-
-      break if $help and found_synopsis and line =~ /^#\s*$/
-
+  if manual || help
+    DATA.read.split("\n").each do |line|
+      puts Regexp.last_match(1).dup if line =~ /^# ?(.*)/
     end
-
     exit 0
   end
 
-
   #
   #  Create the worker, passing it the settings object so it can
   # sort out its own logfile, etc.
   #
   worker = Custodian::Worker.new(settings)
 
-
   #
   #  Single step?
   #
-  if  ENV['SINGLE'] 
+  if  ENV['SINGLE']
     worker.process_single_job
     exit(0)
   end
@@ -144,7 +75,7 @@ if __FILE__ == $PROGRAM_NAME then
   #
   #  Run until we see a failure?
   #
-  if  ENV['FAIL'] 
+  if  ENV['FAIL']
     worker.process_until_fail
     exit(0)
   end
@@ -155,3 +86,43 @@ if __FILE__ == $PROGRAM_NAME then
   worker.run!
 
 end
+
+
+__END__
+#
+# NAME
+#  custodian-dequeue - Execute network tests from the central queue.
+#
+# SYNOPSIS
+#  custodian-dequeue  [ -h | --help ]
+#                     [ -m | --manual]
+#                     [ -f | --fail ]
+#                     [ -s | --single ]
+#                     [ -v | --verbose ]
+#
+# OPTIONS
+#
+#  -h, --help          Show a help message, and exit.
+#
+#  -m, --manual        Show this manual, and exit.
+#
+#  -s, --single        Run a single test and exit.
+#
+#  -f, --fail          Stop running once a single test fails.
+#
+#  -v, --verbose       Be noisy.
+#
+#
+# ABOUT
+#
+# This tool is designed to pull network/protocol-tests from the central queue
+# and execute them one by one.
+#
+# The results of the testing will be sent to a notifier, where they can later
+# be acted upon.
+#
+#
+# AUTHOR
+#
+#  Steve Kemp  <steve@bytemark.co.uk>
+#
diff --git a/bin/custodian-enqueue b/bin/custodian-enqueue
index e8f71f0..f815757 100755
--- a/bin/custodian-enqueue
+++ b/bin/custodian-enqueue
@@ -1,93 +1,41 @@
-#!/usr/bin/ruby -Ilib/ -I../lib/ -rubygems
+#!/usr/bin/ruby -rubygems
 #
-# NAME
-#  custodian-enqueue - Parse tests from a file and enqueue them.
-#
-# SYNOPSIS
-#  custodian-enqueue  [ -h | --help ]
-#                     [ -m | --manual]
-#                     [ -q | --queue NAME]
-#                     [ -f | --file FILE]
-#                     [ -d | --dump ]
-#                     [    | --test ]
-#
-# OPTIONS
-#
-#  -h, --help          Show a help message, and exit.
+# Usage information at the end of the script.
 #
-#  -m, --manual        Show this manual, and exit.
-#
-#  -d, --dump          Dump the parsed tests to the console; don't insert in the queue.
-#
-#  --test              Test the parsing of the given file, alert on errors.
-#
-#  -f, --file FILE     Parse the given configuration file.
-#
-#
-#
-# ABOUT
-#
-# This tool reads a single configuration file and parses it into a
-# series of network & protocol tests.   These tests are then stored in
-# a queue from which workers can retrieve and execute them.
-#
-# The dequeing process may occur up numerous other hosts.
-#
-# CONFIGURATION FILE
-#
-# The configuration file is 99% compatible with that used in the tool
-# custodian replaces.
-#
-#
-# AUTHOR
-#
-#  Steve Kemp  <steve@bytemark.co.uk>
-#
-
 
-
-#
-# Standard modules
-#
 require 'getoptlong'
-
-#
-# Our code.
-#
 require 'custodian/parser'
 require 'custodian/queue'
 require 'custodian/settings'
 
-
-
 #
 #  Entry-point to our code.
 #
-if __FILE__ == $PROGRAM_NAME then
+if __FILE__ == $PROGRAM_NAME
 
-  $help   = false
-  $manual = false
+  help   = false
+  manual = false
 
   begin
     opts = GetoptLong.new(
-                          ['--dump',  '-d', GetoptLong::NO_ARGUMENT],
-                          ['--test',   GetoptLong::NO_ARGUMENT],
-                          ['--file',  '-f', GetoptLong::REQUIRED_ARGUMENT],
-                          ['--help',  '-h', GetoptLong::NO_ARGUMENT],
-                          ['--manual', '-m', GetoptLong::NO_ARGUMENT]
+      ['--dump',  '-d', GetoptLong::NO_ARGUMENT],
+      ['--test',   GetoptLong::NO_ARGUMENT],
+      ['--file',  '-f', GetoptLong::REQUIRED_ARGUMENT],
+      ['--help',  '-h', GetoptLong::NO_ARGUMENT],
+      ['--manual', '-m', GetoptLong::NO_ARGUMENT]
                           )
     opts.each do |opt, arg|
       case opt
       when '--dump' then
-          ENV['DUMP'] = '1'
+        ENV['DUMP'] = '1'
       when '--test' then
-          ENV['TEST'] = '1'
-       when '--file' then
-          ENV['FILE'] = arg
+        ENV['TEST'] = '1'
+      when '--file' then
+        ENV['FILE'] = arg
       when '--help' then
-          $help = true
+        help = true
       when '--manual' then
-          $manual = true
+        manual = true
       end
     end
   rescue StandardError => ex
@@ -95,54 +43,31 @@ if __FILE__ == $PROGRAM_NAME then
     exit
   end
 
-
   #
-  # CAUTION! Here be quality kode.
+  #  Show the help information.
   #
-  if $manual or $help
-
-    # Open the file, stripping the shebang line
-    lines = File.open(__FILE__){|fh| fh.readlines}[1..-1]
-
-    found_synopsis = false
-
-    lines.each do |line|
-
-      line.chomp!
-      break if line.empty?
-
-      if $help and !found_synopsis
-        found_synopsis = (line =~ /^#\s+SYNOPSIS\s*$/)
-        next
-      end
-
-      puts line[2..-1].to_s
-
-      break if $help and found_synopsis and line =~ /^#\s*$/
-
+  if manual || help
+    DATA.read.split("\n").each do |line|
+      puts Regexp.last_match(1).dup if line =~ /^# ?(.*)/
     end
-
     exit 0
   end
 
-
   #
   # Connected to the queue - be it redis or beanstalkd
   #
   settings = Custodian::Settings.instance
   queue = Custodian::QueueType.create(settings.queue_type)
-  if  !queue 
+  unless  queue
     puts "Failed to connect to the #{settings.queue_type} queue"
     exit 1
   end
 
-
   #
   # Create the parser object.
   #
   mon = Custodian::Parser.new
 
-
   #
   # Parse our configuration file.  If there are errors then we'll
   # exit this script.
@@ -156,10 +81,9 @@ if __FILE__ == $PROGRAM_NAME then
   end
 
   mon.jobs.each do |test|
-
-    if  ENV['TEST'] 
+    if  ENV['TEST']
       # nop
-    elsif  ENV['DUMP'] 
+    elsif  ENV['DUMP']
       puts test
     else
       queue.add(test.to_s)
@@ -167,3 +91,51 @@ if __FILE__ == $PROGRAM_NAME then
   end
 
 end
+
+
+__END__
+#
+# NAME
+#  custodian-enqueue - Parse tests from a file and enqueue them.
+#
+# SYNOPSIS
+#  custodian-enqueue  [ -h | --help ]
+#                     [ -m | --manual]
+#                     [ -q | --queue NAME]
+#                     [ -f | --file FILE]
+#                     [ -d | --dump ]
+#                     [    | --test ]
+#
+# OPTIONS
+#
+#  -h, --help          Show a help message, and exit.
+#
+#  -m, --manual        Show this manual, and exit.
+#
+#  -d, --dump          Dump the parsed tests to the console.
+#                      (They are not inserted to the queue.)
+#
+#  --test              Test the parsing of the given file, alert on errors.
+#
+#  -f, --file FILE     Parse the given configuration file.
+#
+#
+#
+# ABOUT
+#
+# This tool reads a single configuration file and parses it into a
+# series of network & protocol tests.   These tests are then stored in
+# a queue from which workers can retrieve and execute them.
+#
+# The dequeing process may occur up numerous other hosts.
+#
+# CONFIGURATION FILE
+#
+# The configuration file is 99% compatible with that used in the tool
+# custodian replaces.
+#
+#
+# AUTHOR
+#
+#  Steve Kemp  <steve@bytemark.co.uk>
+#
diff --git a/bin/custodian-queue b/bin/custodian-queue
index dcb4b9a..fcbf2b3 100755
--- a/bin/custodian-queue
+++ b/bin/custodian-queue
@@ -1,90 +1,47 @@
-#!/usr/bin/ruby -Ilib/ -I../lib/ -rubygems
+#!/usr/bin/ruby -rubygems
 #
-# NAME
-#  custodian-queue - Work with the queue.
-#
-# SYNOPSIS
-#  custodian-queue  [ -h | --help ]
-#                   [ -m | --manual ]
-#                   [ -M | --monitor ]
-#                   [ -f | --flush ]
-#                   [ -s | --stats ]
-#
-# OPTIONS
+# Usage information at the end of the script.
 #
-#  -h, --help          Show a help message, and exit.
-#
-#  -m, --manual        Show this manual, and exit.
-#
-#  -M, --monitor       If the queue size exceeds the threshold report that via an exit code.
-#
-#  -f, --flush         Flush the queue, removing all jobs.
-#
-#  -s, --stats         Show the count of pending jobs.
-#
-#
-# ABOUT
-#
-#  This tool is designed to inspect the beanstalkd queue, or flush the pending
-# jobs from it.
-#
-#
-# AUTHOR
-#
-#  Steve Kemp  <steve@bytemark.co.uk>
-#
-
-
 
-#
-# Standard modules
-#
 require 'getoptlong'
-
-
-#
-# Our code
-#
 require 'custodian/settings'
 require 'custodian/queue'
 
-
 #
 #  Entry-point to our code.
 #
-if __FILE__ == $PROGRAM_NAME then
-
-  $FLUSH   = false
-  $STATS   = false
-  $help    = false
-  $manual  = false
-  $MONITOR = nil
+if __FILE__ == $PROGRAM_NAME
 
+  flush   = false
+  stats   = false
+  help    = false
+  manual  = false
+  monitor = nil
 
   begin
     opts = GetoptLong.new(
-                          ['--flush',   '-f', GetoptLong::NO_ARGUMENT],
-                          ['--help',    '-h', GetoptLong::NO_ARGUMENT],
-                          ['--manual',  '-m', GetoptLong::NO_ARGUMENT],
-                          ['--monitor', '-M', GetoptLong::OPTIONAL_ARGUMENT],
-                          ['--stats',   '-s', GetoptLong::NO_ARGUMENT]
+      ['--flush',   '-f', GetoptLong::NO_ARGUMENT],
+      ['--help',    '-h', GetoptLong::NO_ARGUMENT],
+      ['--manual',  '-m', GetoptLong::NO_ARGUMENT],
+      ['--monitor', '-M', GetoptLong::OPTIONAL_ARGUMENT],
+      ['--stats',   '-s', GetoptLong::NO_ARGUMENT]
                           )
     opts.each do |opt, arg|
       case opt
       when '--monitor' then
-          if  arg 
-              $MONITOR = arg.to_i
-          else
-              $MONITOR = 5000
-          end
+        if  arg
+          monitor = arg.to_i
+        else
+          monitor = 5000
+        end
       when '--stats' then
-          $STATS = true
+        stats = true
       when '--flush' then
-          $FLUSH = true
+        flush = true
       when '--help' then
-          $help = true
+        help = true
       when '--manual' then
-          $manual = true
+        manual = true
       end
     end
   rescue StandardError => ex
@@ -93,31 +50,12 @@ if __FILE__ == $PROGRAM_NAME then
   end
 
   #
-  # CAUTION! Here be quality kode.
+  # Show the help information.
   #
-  if $manual or $help
-
-    # Open the file, stripping the shebang line
-    lines = File.open(__FILE__){|fh| fh.readlines}[1..-1]
-
-    found_synopsis = false
-
-    lines.each do |line|
-
-      line.chomp!
-      break if line.empty?
-
-      if $help and !found_synopsis
-        found_synopsis = (line =~ /^#\s+SYNOPSIS\s*$/)
-        next
-      end
-
-      puts line[2..-1].to_s
-
-      break if $help and found_synopsis and line =~ /^#\s*$/
-
+  if manual || help
+    DATA.read.split("\n").each do |line|
+      puts Regexp.last_match(1).dup if line =~ /^# ?(.*)/
     end
-
     exit 0
   end
 
@@ -130,37 +68,71 @@ if __FILE__ == $PROGRAM_NAME then
   #
   # Alerting on a queue that is too-full?
   #
-  if  !$MONITOR.nil? 
+  unless monitor.nil?
 
     #
     # Find the number of jobs
     #
     jobs = queue.size?
 
-    if  jobs > $MONITOR 
-        exit 1
+    if jobs > monitor
+      exit 1
     else
-        exit 0
+      exit 0
     end
   end
 
-
   #
   # Showing stats?
   #
-  if  $STATS 
-     jobs = queue.size?
-     puts "There are #{jobs || 0} jobs pending."
-     exit(0)
+  if stats
+    jobs = queue.size?
+    puts "There are #{jobs || 0} jobs pending."
+    exit(0)
   end
 
-
   #
   #  Are we flushing the queue?
   #
-  if  $FLUSH 
-    queue.flush!
-  end
-
+  queue.flush! if flush
 
 end
+
+
+__END__
+# NAME
+#  custodian-queue - Work with the queue.
+#
+# SYNOPSIS
+#  custodian-queue  [ -h | --help ]
+#                   [ -m | --manual ]
+#                   [ -M | --monitor ]
+#                   [ -f | --flush ]
+#                   [ -s | --stats ]
+#
+# OPTIONS
+#
+#  -h, --help          Show a help message, and exit.
+#
+#  -m, --manual        Show this manual, and exit.
+#
+#  -M, --monitor       If the queue size exceeds the given threshold
+#                      then report that via an exit code.
+#
+#  -f, --flush         Flush the queue, removing all jobs.
+#
+#  -s, --stats         Show the count of pending jobs.
+#
+#
+# ABOUT
+#
+# This tool is designed to inspect the global queue, and also allows that
+# queue to be flushed of all pending-jobs.
+#
+# The queue may be redis-based, or beanstalkd-based, as defined by the
+# global configuration-file.
+#
+# AUTHOR
+#
+#  Steve Kemp  <steve@bytemark.co.uk>
+#
diff --git a/bin/multi-ping b/bin/multi-ping
index 32fb4ce..7957565 100755
--- a/bin/multi-ping
+++ b/bin/multi-ping
@@ -1,129 +1,104 @@
-#!/usr/bin/ruby -Ilib/ -I../lib/
+#!/usr/bin/ruby -Ilib/
 #
-# NAME
-#   multi-ping - IPv4 and IPv6 ping tool
-#
-#
-# SYNOPSIS
-#  multi-ping  [ -h | --help ] [-m | --manual] hostname
-#
-#
-# OPTIONS
-#
-#  -h, --help      Show a help message, and exit.
-#
-#  -m, --manual    Show this manual, and exit.
-#
-#
-# ABOUT
-#
-#  The multi-ping tool is designed to be IPv4/IPv6-agnostic ping tool,
-# which removes the need to know if you're pinging an IPv4 host or an
-# IPv6 host.
-#
-#  The tool works by resolving the hostname specified upon the command line,
-# and invoking "ping" or "ping6" upon the result - using the correct one for
-# the address family which has been returned.
-#
-#
-# AUTHOR
+# Usage information at the end of the script.
 #
-#  Steve Kemp  <steve@bytemark.co.uk>
-#
-
 
 require 'getoptlong'
 require 'custodian/util/ping'
 
-
-
 #
-#  Options set by the command-line.  These are all global.
+#  Options set by the command-line.
 #
-$help   = false
-$manual = false
+help   = false
+manual = false
 
 opts = GetoptLong.new(
-                      ['--help',   '-h', GetoptLong::NO_ARGUMENT],
-                      ['--manual', '-m', GetoptLong::NO_ARGUMENT])
+  ['--help',   '-h', GetoptLong::NO_ARGUMENT],
+  ['--manual', '-m', GetoptLong::NO_ARGUMENT])
 
 begin
-  opts.each do |opt, arg|
+  opts.each do |opt, _arg|
     case opt
     when '--help' then
-      $help = true
+      help = true
     when '--manual' then
-      $manual = true
+      manual = true
     end
   end
 rescue => err
   # any errors, show the help
   warn err.to_s
-  $help = true
+  help = true
 end
 
-
 #
-# CAUTION! Here be quality kode.
+# Show the help information.
 #
-if $manual or $help
-
-  # Open the file, stripping the shebang line
-  lines = File.open(__FILE__){|fh| fh.readlines}[1..-1]
-
-  found_synopsis = false
-
-  lines.each do |line|
-
-    line.chomp!
-    break if line.empty?
-
-    if $help and !found_synopsis
-      found_synopsis = (line =~ /^#\s+SYNOPSIS\s*$/)
-      next
-    end
-
-    puts line[2..-1].to_s
-
-    break if $help and found_synopsis and line =~ /^#\s*$/
-
+if manual || help
+  DATA.read.split("\n").each do |line|
+    puts Regexp.last_match(1).dup if line =~ /^# ?(.*)/
   end
-
   exit 0
 end
 
-
-
-
-
 #
 #  Get the address to ping.
 #
 hostname = ARGV.shift
 
-
 #
 #  Abort if we don't have a hostname
 #
-if  hostname.nil? 
+if  hostname.nil?
   puts "Usage: #{$PROGRAM_NAME} hostname"
   exit 1
 end
 
-
-
 #
 #  Create the object
 #
 helper = Custodian::Util::Ping.new(hostname)
 
-
 #
 #  Ping the host, via the helper
 #
-if  helper.run_ping 
+if  helper.run_ping
   puts "#{hostname} - #{helper.address} - is alive."
   exit 0
 else
   exit 1
 end
+
+
+__END__
+#
+# NAME
+#   multi-ping - IPv4 and IPv6 ping tool
+#
+#
+# SYNOPSIS
+#  multi-ping  [ -h | --help ] [-m | --manual] hostname
+#
+#
+# OPTIONS
+#
+#  -h, --help      Show a help message, and exit.
+#
+#  -m, --manual    Show this manual, and exit.
+#
+#
+# ABOUT
+#
+#  The multi-ping tool is designed to be IPv4/IPv6-agnostic ping tool,
+# which removes the need to know if you're pinging an IPv4 host or an
+# IPv6 host.
+#
+#  The tool works by resolving the hostname specified upon the command line,
+# and invoking "ping" or "ping6" upon the result - using the correct one for
+# the address family which has been returned.
+#
+#
+# AUTHOR
+#
+#  Steve Kemp  <steve@bytemark.co.uk>
+#