naplug 1.7.1 → 1.9.0

data/README.md

@@ -1,6 +1,6 @@
 # Naplug [![Gem Version](https://badge.fury.io/rb/naplug.png)](http://badge.fury.io/rb/naplug)
 
-*Naplug* is a [Nagios plugin](http://nagiosplug.sourceforge.net/developer-guidelines.html) library for Ruby focused on plugin internals: organization, status, performance data, output and exit code handling. It does not implement any functionality related to option and argument parsing, as there are fine tools already available for this purpose. It aims to ease the task of writing Nagios plugins in Ruby and _handling the paperwork_, allowing the plugin developer to concentrate on the test logic of the plugin. Its internal design is largely modeled after the very excellent [Worlkflow](https://github.com/geekq/workflow) library.
+*Naplug* is a [Nagios plugin](http://nagiosplug.sourceforge.net/developer-guidelines.html) library for Ruby focused on plugin internals: organization, status, performance data, output and exit code handling. It contains (but does not include by default) functionality related to option and argument parsing, allowing plugin developers to use [any of the many fine CLI tools available](https://www.ruby-toolbox.com/categories/CLI_Option_Parsers) for this purpose. It aims to ease the task of writing Nagios plugins in Ruby and _handling the paperwork_, allowing the plugin developer to concentrate on the test logic of the plugin. Some of internal implementation is largely modeled after the very excellent [Worlkflow](https://github.com/geekq/workflow) library.
 
 *Naplug* allows plugins to contain other plugins (referred to as *plugs*), which are a useful abstraction to break up significant tasks that the plugin as a whole must perform in order to determine the state of a service or host. The status and output of these plugs is thus used to determine the overall status of the plugin and build the output depending on said status.
 
@@ -499,7 +499,7 @@ Overriding these will likely cause *Naplug* to misbehave, to say the least.
 
 Other methods can be defined in the class as necessary, and they can be used in the defined plugins or plugs, generally to provide helpers services. These should be defined as `private` or `protected` as necessary.
      
-### Status
+## Status
 
 Status is a special object that represent the status of a plugin for each of the defined states in the [Nagios Plugin Guidelines](http://nagiosplug.sourceforge.net/developer-guidelines.html): `OK`, `WARNING`, `CRITICAL` and `UNKNOWN`. Each of these states is itself an instance method which sets the state, and you can obtain the string and numeric representation through the usual methods `to_s` and `to_i`. The initial (and default) status of a `Status` object is `UNKNOWN`. Statuses are comparable in that larger statuses represent worse states, a feature that will come handy shortly.
 
@@ -537,6 +537,48 @@ which produces
     Comparing statuses:
       status [OK] < status1 [WARNING] is true
 
+## Naplug Helpers
+
+*Naplug* includes helpers, which are not loaded by default.
+
+### `Naplug::Helpers::CLI`
+
+Naplug is very much focused on plugin internals, leaving the work of command-line parsing to external entities. This allows plugin developers to use their preferred choice of parsers, such as [`thor`](http://whatisthor.com), [`Slop`](https://github.com/leejarvis/slop) or `OptionsParser`.
+
+A helper is however built-in, and uses the small and very flexible [*trollop*] library, which must be installed as a gem. To use:
+
+    require 'naplug'
+    require 'naplug/helpers/cli'
+    
+    class FooPlugin
+    
+      VERSION = '1.0.0'
+    
+      include Naplug
+    
+      plugin do |p|
+        ...
+      end
+    end
+    
+    class FooPluginCLI
+    
+      include Naplug::Helpers::CLI
+      
+      opts = options do
+        version FooPlugin::VERSION
+        banner "#{File.basename($0)}"
+        opt :warning, 'number of mtime WARNING seconds (required)', :type => :int, :required => true
+        opt :critical, 'number of mtime CRITICAL seconds (required)', :type => :int, :required => true
+      end
+      
+      plugin = FooPlugin.new opts
+      plugin.exec!
+      
+    end
+    
+Naplug does change the behavior of *Trollop* so that when arguments generate an error, these are handled correctly as a plugin (producing an `UNKNOWN` status).
+
 # Futures
 
 There following are some ideas on future Naplug features.

data/lib/naplug/helpers/cli.rb

@@ -0,0 +1,44 @@
+require 'trollop'
+require 'naplug'
+
+module Naplug
+
+  module Helpers
+
+    module CLI
+
+      def self.included(klass)
+        klass.send :include, InstanceMethods
+        klass.extend ClassMethods
+      end
+
+      module ClassMethods
+        include Trollop
+
+        def with_standard_exception_handling parser
+          begin
+            yield
+          rescue CommandlineError => e
+            plugin = Naplug::Plugin.new :cli, Proc.new { true }, {}
+            plugin.output! e.message
+            print "%s: %s\n" % [plugin.status.to_s,plugin.output]
+            exit plugin.status.to_i
+          rescue HelpNeeded
+            parser.educate
+            exit
+          rescue VersionNeeded
+            puts parser.version
+            exit
+          end
+        end
+      end
+
+      module InstanceMethods
+        def initialize
+        end
+      end
+
+    end
+
+  end
+end

data/lib/naplug/helpers/json_thresholds.rb

@@ -0,0 +1,46 @@
+require 'json'
+
+module Naplug
+
+  module Helpers
+
+    module JSON_Thresholds
+
+      def self.included(klass)
+        klass.extend ClassMethods
+      end
+
+      module ClassMethods
+        def hashify_json_thresholds(*threstag)
+          tag, thresholds_json, thresholds_hash = case threstag.size
+                                                    when 0, 1
+                                                     [nil, threstag[0], {}]
+                                                    else
+                                                     [threstag[1],threstag[0], {}]
+                                                  end
+          plug = nil
+          thresholds_proc = Proc.new do |json_element|
+            case
+              when (json_element.is_a? String and json_element.match(/\d*:\d*:\d*:\d*/))
+                case tag.nil?
+                  when true
+                    thresholds_hash[plug] = Hash[Status.states.zip json_element.split(':',-1).map { |v| v.nil? ? nil : v.to_i } ]
+                  else
+                    thresholds_hash[tag] = Hash[plug, Hash[Status.states.zip json_element.split(':',-1).map { |v| v.nil? ? nil : v.to_i } ]]
+                end
+              when Symbol
+                plug = json_element
+              else
+                nil
+            end
+          end
+          JSON.recurse_proc(JSON.parse(thresholds_json, :symbolize_names => true),&thresholds_proc) if thresholds_json
+          thresholds_hash
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/naplug/helpers.rb

@@ -7,27 +7,6 @@ module Naplug
 
   module Helpers
 
-    module Thresholds
-
-      def hashify_json_thresholds(tag,thres_json=nil)
-        thresholds = { tag => {} }
-        plug = nil
-        thres_proc = Proc.new do |json_element|
-          case
-            when (json_element.is_a? String and json_element.match(/\d*:\d*:\d*:\d*/))
-              thresholds[:main][plug] = Hash[Status.states.zip json_element.split(':',-1).map { |v| v.nil? ? nil : v.to_i } ]
-            when Symbol
-              plug = json_element
-            else
-              nil
-          end
-        end
-        JSON.recurse_proc(JSON.parse(thres_json, :symbolize_names => true),&thres_proc) if thres_json
-        thresholds
-      end
-
-    end
-
     module Hashes
 
       # Thx Avdi Grimm! http://devblog.avdi.org/2009/11/20/hash-transforms-in-ruby/

data/lib/naplug/plugin.rb

@@ -13,8 +13,11 @@ module Naplug
     class DuplicatePlugin < StandardError; end
 
     DEFAULT_META = { :debug => false, :enabled => true }
+    VALID_META_OPTIONS = [ :debug, :state, :description, :parent ]
+
+    def initialize(tag, block, meta)
+      validate_meta_options meta
 
-    def initialize(tag, block, meta = {})
       @tag = tag
       @block = block
       @plugins = Hash.new
@@ -23,7 +26,13 @@ module Naplug
       @_data = OpenStruct.new :status => Status.new, :output => Output.new, :payload => nil, :perfdata => nil
       @_meta = OpenStruct.new DEFAULT_META.merge meta
 
-      begin; instance_eval &block ; rescue => e; nil ; end
+      begin
+        instance_eval &block
+      rescue ArgumentError => e
+        raise
+      rescue
+        nil
+      end
 
     end
 
@@ -56,6 +65,10 @@ module Naplug
       @_meta.parent
     end
 
+    def description
+      @_meta.description
+    end
+
     # true when a plugin contains plugs
     def has_plugins?
       @plugins.empty? ? false : true
@@ -142,9 +155,10 @@ module Naplug
 
     private
 
-    def plugin(tag, &block)
+    def plugin(*tagmeta, &block)
+      tag,meta = tagmeta_grok(tagmeta)
       raise DuplicatePlugin, "duplicate definition of #{tag}" if @plugins.key? tag
-      @plugins[tag] = Plugin.new tag, block, :parent => self
+      @plugins[tag] = Plugin.new tag, block, meta.merge({ :parent => self })
       self.define_singleton_method tag do
         @plugins[tag]
       end
@@ -154,5 +168,33 @@ module Naplug
       @_meta.debug
     end
 
+    def tagmeta_grok(tagmeta)
+      case tagmeta.size
+        when 0
+          [:main, {}]
+        when 1
+          case tagmeta[0]
+            when Symbol
+              [tagmeta[0], {}]
+            when Hash
+              [:main,tagmeta[0]]
+            else
+              raise Naplug::Error, 'ArgumentError on Naplug#plugin'
+          end
+        when 2
+          raise Naplug::Error, 'ArgumentError on Naplug#plugin' unless tagmeta[0].is_a? Symbol and tagmeta[1].is_a? Hash
+          tagmeta[0..1]
+        else
+          raise Naplug::Error, 'ArgumentError on Naplug#plugin'
+      end
+    end
+
+    def validate_meta_options(options)
+      invalid_options = options.keys - VALID_META_OPTIONS
+      if invalid_options.any?
+        raise ArgumentError, "invalid meta option(s): #{invalid_options.join(', ')}"
+      end
+    end
+
   end
 end

data/lib/naplug/version.rb

@@ -1,3 +1,3 @@
 module Naplug
-  VERSION = '1.7.1'
+  VERSION = '1.9.0'
 end

data/lib/naplug.rb

@@ -11,8 +11,6 @@
 #--
 # Naplug::ClassMethods and Naplug::InstanceMethods
 
-
-require 'rubygems'
 require 'naplug/plugin'
 
 module Naplug
@@ -30,9 +28,10 @@ module Naplug
     # Create a metaplugin (which basically contains a tag and a block)
     # @param tag [Symbol] the plugin tag
     # @return [Plugin] a metaplugin
-    def plugin(tag = :main, &block)
+    def plugin(*tagmeta, &block)
+      tag, meta = tagmeta_grok tagmeta
       @plugins = Hash.new unless @plugins
-      @plugins[tag] = create_metaplugin tag, block
+      @plugins[tag] = create_metaplugin tag, meta, block
     end
 
     # A list of plugin tags
@@ -44,12 +43,33 @@ module Naplug
     private
 
     # Create a metaplugin (helper)
-    def create_metaplugin(tag,block)
+    def create_metaplugin(tag,meta,block)
       module_eval do
         define_method "#{tag}".to_sym  do; @plugins[tag];  end    # <tag> methods for quick access to plugins
         define_method "#{tag}!".to_sym do; self.exec! tag; end    # <tag>! methods to involke exec! on a given plugin
       end
-      Plugin.new tag, block, :meta => true, :parent => self
+      Plugin.new tag, block, meta.merge({ :parent => self })
+    end
+
+    def tagmeta_grok(tagmeta)
+      case tagmeta.size
+        when 0
+          [:main, {}]
+        when 1
+          case tagmeta[0]
+            when Symbol
+              [tagmeta[0], {}]
+            when Hash
+              [:main,tagmeta[0]]
+            else
+              raise Naplug::Error, 'ArgumentError on Naplug#plugin'
+          end
+        when 2
+          raise Naplug::Error, 'ArgumentError on Naplug#plugin' unless tagmeta[0].is_a? Symbol and tagmeta[1].is_a? Hash
+          tagmeta[0..1]
+        else
+          raise Naplug::Error, 'ArgumentError on Naplug#plugin'
+      end
     end
 
   end
@@ -168,7 +188,7 @@ module Naplug
 
     def plugins!
       self.class.plugins.each do |tag,plugin|
-        @plugins[tag] = Plugin.new tag, plugin.block
+        @plugins[tag] = Plugin.new tag, plugin.block, {}
       end
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: naplug
 version: !ruby/object:Gem::Version
-  version: 1.7.1
+  version: 1.9.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-26 00:00:00.000000000 Z
+date: 2014-02-27 00:00:00.000000000 Z
 dependencies: []
 description: ! 'A Ruby library for Nagios plugins '
 email: gerir@evernote.com
@@ -18,6 +18,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/naplug/about.rb
+- lib/naplug/helpers/cli.rb
+- lib/naplug/helpers/json_thresholds.rb
 - lib/naplug/helpers.rb
 - lib/naplug/output.rb
 - lib/naplug/performancedata.rb