power_converter 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1ffe8e4ed7f1e0bdafe8e06f34abca7936df05eb
-  data.tar.gz: 7be13e121f7797f707da2627fa048a7117d2888c
+  metadata.gz: 1bd5e2306a30c044d98fadc15a1a330cd485f34f
+  data.tar.gz: ebc9c3bed3649bd24f11fa6564e52a088a766d5a
 SHA512:
-  metadata.gz: 6b61649071f7d32ed30c86ce4f4dc09a1a442f0d49c6ac8d255a7ab03b1e0c2b1326557e559a5e90a5d4b79fadca90c0e3f9628cd10ed05f6e46095cea677b2f
-  data.tar.gz: a25a41c2d57a8241a307905ba9d9e6264d0133888bc56b181b52bddbc3beb0583b4816c7093234499bcd827b21be73c435a583e3c8353786832f76ca312aea33
+  metadata.gz: 53124e4dc414751702a99c3b8be7d61dc31cc275141ddc9a5a9fe0fa192a9890580c022e8190675932ea1406dbc362fa8b0877b8201f4b6f34f74aedb4b22a84
+  data.tar.gz: 93dae5155d1d25aaecac0c218d75a7fa9b734a3e7cf61663d4a427bf0e546d4a9d6a2e1b72c18dfa312debb6853a87a8c034c21582bf3503faf8628e57d19f0b

data/README.md

@@ -1,13 +1,46 @@
 # PowerConverter
 
+[![Gem Version](https://badge.fury.io/rb/power_converter.svg)](http://badge.fury.io/rb/power_converter)
 [![Build Status](https://travis-ci.org/jeremyf/power_converter.png?branch=master)](https://travis-ci.org/jeremyf/power_converter)
 [![Documentation Status](http://inch-ci.org/github/jeremyf/power_converter.svg?branch=master)](http://inch-ci.org/github/jeremyf/power_converter)
 [![APACHE 2 License](http://img.shields.io/badge/APACHE2-license-blue.svg)](./LICENSE)
 
-A placeholder for implementing a conversion module pattern.
+## About
 
-Exposing a means of registering conversions. These can be accessed at the module
-level:
+**PowerConverter** exposes a means for defining a named conversion method.
+
+*What is a conversion method?*
+
+> A well-established Ruby idiom for methods which "do the right thing" to
+> convery any reasonable input value into a desired class.
+>
+> http://devblog.avdi.org/2012/05/07/a-ruby-conversion-idiom/
+
+*Why conversion methods?*
+
+Because software is all about addressing a mapping problem. In my experience
+using conversion methods has provided a means for easing the movement across
+application design boundaries.
+
+*Why use the PowerConverter gem?*
+
+Excellent question.
+
+**The short-answer is consistency**. **PowerConverter** helps you compose
+conversions that have a common form.
+
+**The longer-answer** is again related to consistency. By using a common
+mechanism for definition, I'm hoping to reduce the nuanced variations that come
+from crafting conversions. They all have a very similar shape, and I'd like to
+provide tooling to help keep that shape.
+
+I would much rather focus on other concepts than "is this conversion method
+similar enough to its sibling conversion methods?"
+
+In other words, relying on a common interface for defining a conversion method
+reduces the number surprises when interacting with conversion methods.
+
+## Usage
 
 ```ruby
 PowerConverter.define_conversion_for :boolean do |input|
@@ -19,4 +52,8 @@ PowerConverter.define_conversion_for :boolean do |input|
 end
 
 PowerConverter.convert(object, to: :boolean)
+
+# OR
+
+PowerConverter.convert_to_boolean(object)
 ```

data/lib/power_converter/version.rb

@@ -1,5 +1,5 @@
 # :nodoc:
 module PowerConverter
   # :nodoc:
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/power_converter.rb

@@ -22,10 +22,27 @@ module PowerConverter
     # @param named_converter [#to_s]
     # @param defined_converter_names [Array]
     #
+    # You had one job...to register a converter. Now you get an exception.
+    #
     # @example
     #   raise ConverterNotFoundError.new(:boolean, [:hello, :world])
     def initialize(named_converter, defined_converter_names)
-      super("Unable to find PowerConverter for #{named_converter} in #{defined_converter_names.inspect}")
+      super("Unable to find PowerConverter for #{named_converter} in #{defined_converter_names.inspect}.")
+    end
+  end
+
+  # When you tried to convert something and it just won't convert, this is a
+  # great exception to raise.
+  class ConversionError < RuntimeError
+    # @param value [Object]
+    # @param named_converter [#to_s]
+    #
+    # Do or do not. There is no try.
+    #
+    # @example
+    #   raise ConversionError.new(:boolean, [:hello, :world])
+    def initialize(value, named_converter)
+      super("Unable to convert #{value.inspect} to '#{named_converter}'.")
     end
   end
 
@@ -37,6 +54,10 @@ module PowerConverter
   # Responsible for defining a conversion method and a "shovel-ready" conversion
   # module; because maybe you want a mixin for convenience reasons.
   #
+  # @note If your defined converter returns `nil`, it is assumed if the
+  #   conversion failed and a [PowerConverter::ConversionError] exception should
+  #   be thrown.
+  #
   # @param named_conversion [String,Symbol] the name of the conversion that you
   #   are declaring.
   # @param converter [#call] the callable object that will perform the
@@ -55,6 +76,10 @@ module PowerConverter
   #       true
   #     end
   #   end
+  #
+  #   PowerConverter.convert(object, to: :boolean)
+  #   PowerConverter.convert_to_boolean(object)
+  #
   # @see http://devblog.avdi.org/2012/05/07/a-ruby-conversion-idiom/ Avdi
   #   Grimm's post on "A Ruby Conversion Idiom"
   #
@@ -72,27 +97,45 @@ module PowerConverter
   # @api public
   # @since 0.0.1
   #
-  # Convert the given `value` via the named `:to` converter.
+  # Convert the given `value` via the named `:to` converter. As a short-circuit
+  # if the given `value` publicly responds to a `to_<named_converter>` it will
+  # use that.
   #
   # @param value [Object] the thing that you will be converting
   # @param [Hash] options the options used to perform the conversion
   # @option options [Symbol] :to the named_conversion that has been registered
   #
+  # @return [Object] the resulting converted object
+  #
   # @raise [ConverterNotFoundError] if the named converter is not found
+  # @raise [ConversionError] if the named converter returned a nil value
   #
   # @see PowerConverter.define_conversion_for
   #
   # @example
   #   PowerConverter.convert('true', to: :boolean)
   #
-  # @todo I want to:
-  #   * raise an exception if I'm unable to convert an object
-  #   * auto-handle :to_<named_conversion> so I don't need to worry about
-  #     registering that.
+  # @example
+  #   class Foo
+  #     def to_bar
+  #       :hello_world
+  #     end
+  #   end
+  #
+  #   PowerConverter.convert(Foo.new, to: :bar)
+  #   => :hello_world
+  #
   def convert(value, options = {})
-    converter_for(options.fetch(:to)).call(value)
+    named_converter = options.fetch(:to)
+    return value.public_send("to_#{named_converter}") if value.respond_to?("to_#{named_converter}", false)
+    returning_value = converter_for(named_converter).call(value)
+    return returning_value unless returning_value.nil?
+    fail ConversionError.new(value, named_converter)
   end
 
+  # :nodoc:
+  CONVERSION_METHOD_PREFIX = "convert_to_".freeze
+
   # @api public
   # @since 0.0.1
   #
@@ -113,11 +156,16 @@ module PowerConverter
   #       convert_to_boolean(@bar)
   #     end
   #   end
+  #
+  # @todo Allow for the inclusion of multiple power converter named types.
   def module_for(named_conversion)
-    converter = converter_for(named_conversion)
     Module.new do
-      define_method("convert_to_#{named_conversion}", &converter)
-      private "convert_to_#{named_conversion}"
+      # HACK: I'd prefer to not lean on calling the underlying convert method
+      # which means I will likely need some converter builder behavior.
+      define_method("#{CONVERSION_METHOD_PREFIX}#{named_conversion}") do |value|
+        PowerConverter.convert(value, to: named_conversion)
+      end
+      private "#{CONVERSION_METHOD_PREFIX}#{named_conversion}"
     end
   end
 
@@ -152,4 +200,36 @@ module PowerConverter
   def defined_converter_names
     @defined_conversions.keys
   end
+
+  # :nodoc:
+  CONVERSION_METHOD_REGEXP = /\A#{CONVERSION_METHOD_PREFIX}(.*)\Z/.freeze
+
+  # :nodoc:
+  def method_missing(method_name, *args, &block)
+    named_converter = extract_named_converter_from(method_name)
+    if named_converter
+      convert(*args, to: named_converter)
+    else
+      super
+    end
+  end
+  private_class_method :method_missing
+
+  # :nodoc:
+  def extract_named_converter_from(method_name)
+    match = method_name.to_s.match(CONVERSION_METHOD_REGEXP)
+    match.captures[0] if match
+  end
+  private_class_method :extract_named_converter_from
+
+  # :nodoc:
+  def respond_to_missing?(method_name, include_private = false)
+    named_converter = extract_named_converter_from(method_name)
+    if named_converter
+      @defined_conversions.key?(named_converter.to_s)
+    else
+      super
+    end
+  end
+  private_class_method :respond_to_missing?
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: power_converter
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Jeremy Friesen