pluginator 0.11.3 → 0.11.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b6454fa655abb05e55461de618af2de74dcdecf1
-  data.tar.gz: eae4963322e3dd0ea9892c1965c5384131f728b8
+  metadata.gz: a42be419608abc90291c8358a4f23b1e43165cec
+  data.tar.gz: baa6ea7161c799f1455cc31fff04f4be8e594794
 SHA512:
-  metadata.gz: 5a7e5992fb6a1203cb9a45681e8719b2d7a9836ffafeb1312b866275c1b9973d95bbdbba4ecd83ba8e4ec9d6ab0f6d83698dc39ece10dffd7566b73f5be783f8
-  data.tar.gz: 0f19687c93b7ba4b14ac848308bdbd5eb4ee15903b29333c6f1880e845d742cde3a7a53090380596ca2121b8a267907a7386ac22c07113774e019c2b07692979
+  metadata.gz: 8cf984f2cb328242a966ae4cd58b4e19d2314689c00bac2a08356149ef8ea98bea0ef4864f39af033f79f4031b573c59b6b97dd0199280c320bf6c25c2441414
+  data.tar.gz: eea32d7a0e76329967ff1a9ef62d9cf3b92fc40433997148ccb5408c77d4f7956d829d3141daacd4428ca88d7a1640a2b5dc0046366fe01a9fd20d09ae54fb4a

data/README.md

@@ -63,6 +63,16 @@ plugins.first_ask( "<type>", "method_to_call", *params) => plugin or nil
 plugins.first_ask!("<type>", "method_to_call", *params) => plugin or exception PluginatorError
 ```
 
+### First class
+
+Find first plugin that clas matches the given name.
+
+```ruby
+plugins = Pluginator.find("<group>", extends: %i{first_class})
+plugins.first_class( "<type>", "<name>") => plugin or nil
+plugins.first_class!("<type>", "<name>") => plugin or exception PluginatorError
+```
+
 ### Matching
 
 Map array of names to available plugins.
@@ -73,6 +83,12 @@ plugins.matching( "<type>", [<array_of_names>]) => [plugins] # nil for missing o
 plugins.matching!("<type>", [<array_of_names>]) => [plugins] or exception PluginatorError
 ```
 
+## Exceptions
+
+- `PluginatorError` - base error for all Pluginator errors
+- `MissingPlugin`   - raised when plugin can not be found, generated by `*!` methods
+- `MissingType`     - raised when type   can not be found, generated by `*!` methods
+
 ## Examples
 
 ### Example 1 - task plugins

data/lib/pluginator.rb

@@ -2,6 +2,12 @@ require_relative "pluginator/extendable_autodetect"
 require_relative "pluginator/version"
 
 module Pluginator
+  # Find plugins for the given group
+  #
+  # @param group [String] name of plugins group
+  # @param type [String] optional name of type to load
+  # @param extends optional list of extension to extend into pluginator instance
+  # @return instance of Pluginator
   def self.group(group, type: nil, extends: [])
     Pluginator::ExtendableAutodetect.new(group, type: type, extends: extends)
   end

data/lib/pluginator/autodetect.rb

@@ -5,6 +5,10 @@ require_relative "name_converter"
 module Pluginator
   class Autodetect < Group
 
+    # Automatically load plugins for given group (and type)
+    #
+    # @param group [String] name of the plugins group
+    # @param type [String] optional name of the plugin type
     def initialize(group, type: nil)
       super(group)
       setup_autodetect(type)

data/lib/pluginator/errors.rb

@@ -1,4 +1,6 @@
 module Pluginator
+
+  # base error for all Pluginator errors
   class PluginatorError < RuntimeError
   private
     def list_to_s(list)
@@ -6,13 +8,20 @@ module Pluginator
     end
   end
 
+  # raised when plugin can not be found, generated by `*!` methods
   class MissingPlugin < PluginatorError
+    # @param type [String] type of the loaded plugin
+    # @param name [String] name of the loaded plugin
+    # @param list [Array]  list of available plugins
     def initialize(type, name, list)
       super("Can not find plugin '#{name}' in #{list_to_s(list)} for type '#{type}'.")
     end
   end
 
+  # raised when type can not be found, generated by `*!` methods
   class MissingType < PluginatorError
+    # @param type [String] type of the loaded plugin
+    # @param list [Array]  list of available types
     def initialize(type, list)
       super("Can not find type '#{type}' in #{list_to_s(list)}.")
     end

data/lib/pluginator/extendable_autodetect.rb

@@ -3,11 +3,20 @@ require_relative "autodetect"
 module Pluginator
   class ExtendableAutodetect < Autodetect
 
+    # Automatically load plugins for given group (and type)
+    # Extend instance with extensions if given.
+    #
+    # @param group [String] name of the plugins group
+    # @param type [String] optional name of the plugin type
+    # @param extends optional list of extension to extend into pluginator instance
     def initialize(group, type: nil, extends: [])
       super(group, type: type)
       extend_plugins(extends)
     end
 
+    # Extend pluginator instance with given extensions
+    #
+    # @param extends list of extension to extend into pluginator instance
     def extend_plugins(extends)
       extensions_matching(extends).each do |plugin|
         extend plugin

data/lib/pluginator/group.rb

@@ -1,19 +1,28 @@
 module Pluginator
   class Group
+    # Group name used for plugins
     attr_reader :group
 
+    # @param group [String] name of the plugins group
     def initialize(group)
       setup_group(group)
     end
 
+    # @param [String] type of plugins to select
+    # @return [Array] list of plugins for type
     def [](type)
       @plugins[type.to_s]
     end
 
+    # @return [Array] list of plugin types loaded
     def types
       @plugins.keys
     end
 
+    # Register a new plugin, can be used to load custom plugins
+    #
+    # @param type [String] type for the klass
+    # @param klass [Class] klass of the plugin to add
     def register_plugin(type, klass)
       type = type.to_s
       @plugins[type] ||= []

data/lib/pluginator/version.rb

@@ -1,3 +1,4 @@
 module Pluginator
-  VERSION = "0.11.3"
+  # Version of Pluginator
+  VERSION = "0.11.4"
 end

data/lib/plugins/pluginator/extensions/conversions.rb

@@ -1,10 +1,15 @@
 module Pluginator::Extensions
   module Conversions
+
+    # converts class name to a file name
     def class2string( klass )
       klass.to_s.gsub(/([A-Z])/m){|match| "_#{$1.downcase}" }[1..-1]
     end
+
+    # converts file name to a class name
     def string2class( str )
       str.to_s.capitalize.gsub(/_(.)/){ $1.upcase }
     end
+
   end
 end

data/lib/plugins/pluginator/extensions/first_ask.rb

@@ -4,13 +4,21 @@ module Pluginator::Extensions
   module FirstAsk
     include PluginsMap
 
+    # Call a method on plugin and return first one that returns `true`.
+    #
+    # @param type [String] name of type to search for plugins
+    # @param method_name [Symbol] name of the method to execute
+    # @param *params [Array] params to pass to the called method
+    # @return The first plugin that method call returns true
     def first_ask(type, method_name, *params)
       @plugins[type] or return nil
       @plugins[type].detect do |plugin|
-        plugin.public_send(method_name, *params)
+        plugin.public_send(method_name.to_sym, *params)
       end
     end
 
+    # Call a method on plugin and return first one that returns `true`.
+    # Behaves like `first_ask` but throws exceptions if can not find anything.
     def first_ask!(type, method_name, *params)
       @plugins[type] or raise Pluginator::MissingType.new(type, @plugins.keys)
       @plugins[type].detect do |plugin|

data/lib/plugins/pluginator/extensions/first_class.rb

@@ -6,10 +6,17 @@ module Pluginator::Extensions
     include PluginsMap
     include Conversions
 
+    # Find first plugin that clas matches the given name.
+    #
+    # @param type [String] name of type to search for plugins
+    # @param klass [Symbol or String] name of the searched class
+    # @return The first plugin that matches the klass
     def first_class(type, klass)
       (plugins_map(type) || {})[string2class(klass)]
     end
 
+    # Find first plugin that clas matches the given name.
+    # Behaves like `first_class` but throws exceptions if can not find anything.
     def first_class!(type, klass)
       @plugins[type] or raise Pluginator::MissingType.new(type, @plugins.keys)
       klass = string2class(klass)

data/lib/plugins/pluginator/extensions/matching.rb

@@ -6,12 +6,19 @@ module Pluginator::Extensions
     include PluginsMap
     include Conversions
 
+    # Map array of names to available plugins.
+    #
+    # @param type [String] name of type to search for plugins
+    # @param list [Array] list of plugin names to load
+    # @return [Array] list of loaded plugins
     def matching(type, list)
       list.map do |plugin|
         (plugins_map(type) || {})[string2class(plugin)]
       end
     end
 
+    # Map array of names to available plugins.
+    # Behaves like `matching` but throws exceptions if can not find anything.
     def matching!(type, list)
       @plugins[type] or raise Pluginator::MissingType.new(type, @plugins.keys)
       list.map do |plugin|

data/lib/plugins/pluginator/extensions/plugins_map.rb

@@ -1,5 +1,9 @@
 module Pluginator::Extensions
   module PluginsMap
+    # provide extra map of plugins with symbolized names as keys
+    #
+    # @param type [String] name of type to generate the map for
+    # @return [Hash] map of the names and plugin classes
     def plugins_map( type )
       @plugins_map ||= {}
       type = type.to_s

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pluginator
 version: !ruby/object:Gem::Version
-  version: 0.11.3
+  version: 0.11.4
 platform: ruby
 authors:
 - Michal Papis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-11 00:00:00.000000000 Z
+date: 2013-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake