necromancer 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f9c37da594bf2020bd875ad6a46514c1d20b7d23
-  data.tar.gz: f351c2bbbd62d9f4780306897ea5f09983607af7
+  metadata.gz: a1c2f7a7dfa509891b8a6e9b54b0dc1c06220bd6
+  data.tar.gz: 0e4645b6d70af9782ded19b153937cb35ae29ca1
 SHA512:
-  metadata.gz: 71b242fd171277c210324744d09d80702af4f718c675f747b997bfb8ec1bb9525c2f9a4bb4de5c6a5de6a2605248e02b576956a31cfd3cc7fb51ea2bb6bf1988
-  data.tar.gz: 2a0cfcb08fb44936ad433903a2d12024d31f615b8fafcbc3100c2a0ab56c253e6d96c9432373ce1c9cd74a47bab2ab948bcae886874824936885641fbeeb54f8
+  metadata.gz: b3e8624ae93d5dea444a1948fecee7be8dfdcdc24b04e4caca39dd93d22214b2035f124de5fdd360ee1af62bfce87dbadd20aa0a13496b7003b104cc3c879de6
+  data.tar.gz: c61f41045c0709a96f7e1d81dce673260f4410ffd91f6d69febf8de0f334d3c8634bb74b20efa6fd8ad88172ad3748bcb5e9e5c6d988c684344759f7159a7a89

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+0.2.0 (December 7, 2014)
+
+* Add #fail_conversion_type to Converter and use in converters
+* Add DateTimeConverters
+* Change IntegerConverters & FloatConverters into Numeric Converters
+* Add string to numeric type conversion

data/README.md

@@ -13,10 +13,15 @@
 
 **Necromancer** provides independent type conversion component for [TTY](https://github.com/peter-murach/tty) toolkit.
 
+## Motivation
+
+Conversion between Ruby core types frequently comes up in projects but is solved by half-baked solutions. This library aims to provide an independent and extensible API to support a robust and generic way to convert between core Ruby types.
+
 ## Features
 
 * Simple and expressive API
 * Ability to specify own converters
+* Ability to compose conversions out of simpler ones
 * Support conversion of custom defined types
 
 ## Installation
@@ -40,32 +45,48 @@ Or install it yourself as:
 * [1. Usage](#1-usage)
 * [2. Interface](#2-interface)
   * [2.1 convert](#21-convert)
-  * [2.1 can?](#22-can)
+  * [2.2 from](#22-from)
+  * [2.3 to](#23-to)
+  * [2.4 can?](#24-can)
 * [3. Converters](#3-converters)
+  * [3.1 Array](#31-array)
+  * [3.2 Boolean](#32-boolean)
+  * [3.3 Hash](#33-hash)
+  * [3.4 Numeric](#34-numeric)
+  * [3.5 Range](#35-range)
+  * [3.6 Custom](#36-custom)
+    * [3.6.1 Using an Object](#361-using-an-object)
+    * [3.6.2 Using a Proc](#362-using-a-proc)
 
 ## 1. Usage
 
-**Necromancer** requires you to instatiate it like so:
+**Necromancer** requires you to instatiate it:
 
 ```ruby
 converter = Necromancer.new
 ```
 
-Once initialize **Necromancer** knows how to handle numerous conversions.
+Once initialized **Necromancer** knows how to handle numerous conversions and also allows you to add your custom type [converters](#35-custom).
 
-For example, to convert a string to a range type:
+For example, to convert a string to a [range](#34-range) type:
 
 ```ruby
 converter.convert('1-10').to(:range)  # => 1..10
 ```
 
-In order to handle boolean conversions:
+In order to handle [boolean](#32-boolean) conversions:
 
 ```ruby
 converter.convert('t').to(:boolean)   # => true
 ```
 
-or get array elements into numeric type:
+To convert string to [numeric](#34-numeric) value:
+
+```ruby
+converter.convert('10e1').to(:numeric)  # => 100
+```
+
+or get [array](#31-array) elements into numeric type:
 
 ```ruby
 converter.convert(['1', '2.3', '3.0']).to(:numeric)  # => [1, 2.3, 3.0]
@@ -77,13 +98,72 @@ However, if you want to tell **Necromancer** about source type use `from`:
 converter.convert(['1', '2.3', '3.0']).from(:array).to(:numeric) # => [1, 2.3, 3.0]
 ```
 
-## 2. Interaface
+## 2. Interface
+
+**Necromancer** will perform conversions on the supplied object through use of `convert`, `from` and `to` methods.
 
 ### 2.1 convert
 
-### 2.2 can?
+For the purpose of divination, **Necromancer** uses `convert` method to turn source type into target type. For example, in order to convert a string into a range type do:
+
+```ruby
+converter.convert('1,10').to(:range)  #  => 1..10
+```
+
+Alternatively, you can use block:
+
+```ruby
+converter.convert { '1,10' }.to(:range) # => 1..10
+```
+
+### 2.2 from
+
+To specify conversion source type use `from` method:
+
+```ruby
+converter.convert('1.0').from(:string).to(:numeric)
+```
+
+In majority of cases you do not need to specify `from` as the type will be inferred from the `convert` method argument and then appropriate conversion will be applied to result in `target` type such as `:numeric`. However, if you do not control the input to `convert` and want to ensure consistent behaviour please use `from`.
+
+The source parameters are:
+
+* :array
+* :boolean
+* :float
+* :integer
+* :numeric
+* :range
+* :string
+
+### 2.3 to
+
+To convert objects between types, **Necromancer** provides several target types. The `to` method allows you to pass target as an argument to perform actual conversion:
+
+```ruby
+converter.convert('yes').to(:boolean)   # => true
+```
+
+By default, when target conversion fails the orignal value is returned. However, you can pass `strict` as an additional argument to ensure failure when conversion cannot be performed:
+
+```ruby
+converter.convert('1a').to(:integer, strict: true)
+# => raises Necromancer::ConversionTypeError
+```
+
+The target parameters are:
+
+* :array
+* :boolean
+* :float
+* :integer
+* :numeric
+* :range
+* :string
 
-To verify that a a given conversion can be handled by **Necormancer** call `can?` with the `source` and `target` of the desired conversion.
+### 2.4 can?
+
+To verify that a given conversion can be handled by **Necormancer** call `can?` with the `source` and `target` of the desired conversion.
 
 ```ruby
 converter = Necromancer.new
@@ -93,41 +173,171 @@ converter.can?(:unknown, :integer)  # => false
 
 ## 3. Converters
 
-### 3.1 Custom
+**Necromancer** flexibility means you can register your own converters or use the already defined converters for such types as 'Array', 'Boolean', 'Hash', 'Numeric', 'Range'.
+
+### 3.1 Array
 
-### 3.2 Array
+The **Necromancer** allows you to transform string into an array object:
 
 ```ruby
-converter.convert(['1', '2.3', '3.0']).to(:numeric)
+converter.call('a, b, c')  # => ['a', 'b', 'c']
 ```
 
+If the string is a list of separated numbers, they will be converted to their respective numeric types:
+
+```ruby
+converter.call('1 - 2 - 3')  # => [1, 2, 3]
+```
+
+You can also convert array containing string objects to array containing numeric values:
+
 ```ruby
 converter.convert(['1', '2.3', '3.0']).from(:array).to(:numeric)
 ```
 
-Raises error when in strict mode
+or simply:
 
 ```ruby
-converter.convert(['1', '2.3', false]).from(:array).to(:numeric)
-# => Necromancer::ConversionError: false cannot be converter to numeric value
+converter.convert(['1', '2.3', '3.0']).to(:numeric)
 ```
 
-Returns value when in non strict mode
+When in `strict` mode the conversion will raise a `Necromancer::ConversionTypeError` error like so:
 
 ```ruby
-converter.convert(['1', '2.3', false]).from(:array).to(:numeric)
+converter.convert(['1', '2.3', false]).to(:numeric, strict: true)
+# => Necromancer::ConversionTypeError: false cannot be converted from `array` to `numeric`
+```
+
+However, in `non-strict` mode the value will be simply returned unchanged:
+
+```ruby
+converter.convert(['1', '2.3', false]).to(:numeric, strict: false)
 # => [1, 2.3, false]
 ```
 
-### 3.3 Range
+### 3.2 Boolean
+
+The **Necromancer** allows you to convert a string object to boolean object. The `1`, `'1'`, `'t'`, `'T'`, `'true'`, `'TRUE'`, `'y'`, `'Y'`, `'yes'`, `'Yes'`, `'on'`, `'ON'` values are converted to `TrueClass`.
+
+```ruby
+converter.convert('yes').to(:boolean)  # => true
+```
+
+Similarly, the `0`, `'0'`, `'f'`, `'F'`, `'false'`, `'FALSE'`, `'n'`, `'N'`, `'no'`, `'No'`, `'off'`, `'OFF'` values are converted to `FalseClass`.
+
+```ruby
+converter.convert('no').to(:boolean) # => false
+```
+
+You can also convert an integer object to boolean:
+
+```ruby
+converter.convert(1).to(:boolean)  # => true
+converter.convert(0).to(:boolean)  # => false
+```
 
-### 3.4 Hash
+### 3.3 Hash
 
 ```ruby
 converter.convert({ x: '27.5', y: '4', z: '11'}).to(:numeric)
 # => { x: 27.5, y: 4, z: 11}
 ```
 
+### 3.4 Numeric
+
+**Necromancer** comes ready to convert all the primitive numeric values.
+
+To convert a string to a float do:
+
+```ruby
+converter.convert('1.2a').to(:float)  #  => 1.2
+```
+
+Conversion to numeric in strict mode raises `Necromancer::ConversionTypeError`:
+
+```ruby
+converter.convert('1.2a').to(:float, strict: true) # => raises error
+```
+
+To convert a string to an integer do:
+
+```ruby
+converter.convert('1a').to(:integer)  #  => 1
+```
+
+However, if you want to convert string to an appropriate matching numeric type do:
+
+```ruby
+converter.convert('1e1').to(:numeric)   # => 10
+```
+
+### 3.5 Range
+
+**Necromancer** is no stranger to figuring out ranges from strings. You can pass `,`, `-`, `..`, `...` characters to denote ranges:
+
+```ruby
+converter.convert('1,10').to(:range)  # => 1..10
+```
+
+or to create a range of letters:
+
+```ruby
+converter.convert('a-z').to(:range)   # => 'a'..'z'
+```
+
+### 3.6 Custom
+
+#### 3.6.1 Using an Object
+
+Firstly, you need to create a converter that at minimum requires to specify `call` method that will be invoked during conversion:
+
+```ruby
+UpcaseConverter = Struct.new(:source, :target) do
+  def call(value, options)
+    value.upcase
+  end
+end
+```
+
+Then you need to specify what type conversions this converter will support. For example, `UpcaseConverter` will allow a string object to be converted to a new string object with content upper cased. This can be done:
+
+```ruby
+upcase_converter = UpcaseConverter.new(:string, :upcase)
+```
+
+**Necromancer** provides the `register` method to add converter:
+
+```ruby
+converter = Necromancer.new
+converter.register(upcase_converter)   # => true if successfully registered
+```
+
+Finally, by invoking `convert` method and specifying `:upcase` as the target for the conversion we achieve the result:
+
+```ruby
+converter.convert('magic').to(:upcase)   # => 'MAGIC'
+```
+
+#### 3.6.2 Using a Proc
+
+Using a Proc object you can create and immediately register a converter. You need to pass `source` and `target` of the conversion that will be used later on to match the conversion. The `convert` allows you to specify the actual conversion in block form. For example:
+
+```ruby
+converter = Necromancer.new
+
+converter.register do |c|
+  c.source= :string
+  c.target= :upcase
+  c.convert = proc { |value, options| value.upcase }
+end
+```
+
+Then by invoking the `convert` method and passing the `:upcase` conversion type you can transform the string like so:
+
+```ruby
+converter.convert('magic').to(:upcase)   # => 'MAGIC'
+```
+
 ## Contributing
 
 1. Fork it ( https://github.com/peter-murach/necromancer/fork )

data/lib/necromancer.rb

@@ -1,13 +1,16 @@
 # coding: utf-8
 
+require 'forwardable'
+require 'date'
+
 require 'necromancer/conversions'
 require 'necromancer/context'
 require 'necromancer/converter'
 require 'necromancer/null_converter'
 require 'necromancer/converters/array'
 require 'necromancer/converters/boolean'
-require 'necromancer/converters/float'
-require 'necromancer/converters/integer'
+require 'necromancer/converters/date_time'
+require 'necromancer/converters/numeric'
 require 'necromancer/converters/range'
 require 'necromancer/conversion_target'
 require 'necromancer/version'
@@ -19,6 +22,14 @@ module Necromancer
   # Raised when conversion type is not available
   NoTypeConversionAvailableError = Class.new(StandardError)
 
+  # Create a conversion instance
+  #
+  # @example
+  #   converter = Necromancer.new
+  #
+  # @return [Context]
+  #
+  # @api private
   def new
     Context.new
   end

data/lib/necromancer/context.rb

@@ -5,6 +5,10 @@ module Necromancer
   #
   # @api public
   class Context
+    extend Forwardable
+
+    def_delegators :"@conversions", :register
+
     # Create a context
     #
     # @api private

data/lib/necromancer/conversions.rb

@@ -30,7 +30,8 @@ module Necromancer
     def load
       ArrayConverters.load(self)
       BooleanConverters.load(self)
-      IntegerConverters.load(self)
+      DateTimeConverters.load(self)
+      NumericConverters.load(self)
       RangeConverters.load(self)
     end
 

data/lib/necromancer/converter.rb

@@ -28,6 +28,17 @@ module Necromancer
       end.new
     end
 
+    # Fail with conversion type error
+    #
+    # @param [Object] value
+    #   the value that cannot be converted
+    #
+    # @api private
+    def fail_conversion_type(value)
+      fail ConversionTypeError, "'#{value}' could not be converted " \
+                                "from `#{source}` into `#{target}` "
+    end
+
     attr_accessor :source
 
     attr_accessor :target

data/lib/necromancer/converters/array.rb

@@ -1,43 +1,51 @@
 # coding: utf-8
 
 module Necromancer
+  # Container for Array converter classes
   module ArrayConverters
+    # An object that converts a String to an Array
     class StringToArrayConverter < Converter
-
+      # Convert string value to array
+      #
+      # @example
+      #   converter.call('a, b, c')  # => ['a', 'b', 'c']
+      #
       # @example
-      #   converter.call('1,2,3')  # => ['1', '2', '3']
+      #   converter.call('1 - 2 - 3')  # => [1, 2, 3]
       #
       # @api public
       def call(value, options = {})
+        strict = options.fetch(:strict, false)
         case value.to_s
-        when /^((\d+)(\s*(,)\s*)?)+$/
+        when /^\s*?((\d+)(\s*(,|-)\s*)?)+\s*?$/
           value.to_s.split($4).map(&:to_i)
-        when /^((\w)(\s*,\s*)?)+$/
-          value.to_s.split(',')
+        when /^((\w)(\s*(,|-)\s*)?)+$/
+          value.to_s.split($4)
         else
-          fail ConversionTypeError, "#{value} could not be converted " \
-                                    "from #{source} into `#{target}`"
+          if strict
+            fail_conversion_type(value)
+          else
+            Array(value)
+          end
         end
       end
     end
 
+    # An object that converts an Array to a numeric
     class ArrayToNumericConverter < Converter
+      # Convert an array to a numeric value
+      #
+      # @example
+      #   converter.call(['1', '2.3', '3.0])  # => [1, 2.3, 3.0]
+      #
+      # @param [Object] value
+      #   the value to convert
+      #
+      # @api public
       def call(value, options = {})
-        strict = options.fetch(:strict, false)
+        numeric_converter = NumericConverters::StringToNumericConverter.new(:string, :numeric)
         value.reduce([]) do |acc, el|
-          acc << case el.to_s
-          when /^\d+\.\d+$/
-            el.to_f
-          when /^\d+$/
-            el.to_i
-          else
-            if strict
-              raise ConversionTypeError, "#{value} could not be converted " \
-                                        " from `#{source}` into `#{target}`"
-            else
-              el
-            end
-          end
+          acc << numeric_converter.call(el, options)
         end
       end
     end