traitorous 0.6.1 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ce24a9926d5a1a1473d4ecce829f5ae67753747e
-  data.tar.gz: 935ffb3bb8ace183357d11db17ed1b9a45a07cd8
+  metadata.gz: 96b54f11016e53adedd46e355dda6e15df91ba0f
+  data.tar.gz: 16d6ae6e551d2a8a636667e05dae8a0187347539
 SHA512:
-  metadata.gz: e4d983bdef166b6f527e01ab327d8e1ecdade88fec74f372bb0d534a31833ddbdf1921a23457cfe2b9fb16136f1547fe32dd1b92cf623c0853b6cd82906d5705
-  data.tar.gz: 5df97df341451212529e99b632aa18267c4a74648aa4f074e6be9ee2184617b8a830c5d71b40b76151907ff18014e600a7aea30873aa8ba5c06e0839b2a73a38
+  metadata.gz: e167111bfa664852ed9a3ca79742196f3744b02464912dea3aa079c0468f8a5ef5b59a4caaab112760129eb03b8833aa47ef9b6c4fe22e33b8962cac444ab5fd
+  data.tar.gz: 28f02d34b627d998df66e5b01923b5925ce5f2a546c7b3f16f2018ab0183b3f5ec7c8b5aefb9f849dd5b894ee336f9b322dbb992fe42989c4a15bd4298e682e6

data/README.md

@@ -16,8 +16,10 @@ The converters can be used to help (de)serialize, set default values, do
 validations and translations.  The converter's job is to be able to import a 
 value, instantiating into classes and assigning values.  
 
-I took a lot of inspiration from [virtus](https://github.com/solnic/virtus).
+No type information is included in a trait.  Only the Converter that will
+import and export it.
 
+I took a lot of inspiration from [virtus](https://github.com/solnic/virtus).
 
 ## Installation
 
@@ -41,7 +43,9 @@ Or install it yourself as:
 
     # see spec/
     require 'traitorous'
-    
+  
+    # trait converters default to Convert.skip which is a converter that just
+    # passes through it's data unchanged.
     class Ruin
       include Traitorous
       include Traitorous::Equality
@@ -63,12 +67,16 @@ Or install it yourself as:
     puts Ruin.new(r.export) == r
     # true
     
+    # the Convert.default converter provides a default value if data is falsey
+    # the Convert.model converter instantiates the class given as a new object
+    #   using data, if the 2nd arg == :array or [], each element of the array is
+    #   instantiated.
     class Area
       include Traitorous
       include Traitorous::Equality
       trait :name
-      trait :size, Converter::DefaultValueStatic.new('sub-continent')
-      trait :ruins, Converter::UniformArray.new(Ruin)
+      trait :size, Convert.default('sub-continent')
+      trait :ruins, Convert.model(Ruin, :array) # or Convert.array(Convert.call_on(Ruin))
     end
     
     area = Area.new(
@@ -96,51 +104,113 @@ in a simple form ready to save.
 This system should be flexible enough to account for an large variety of data
 structures that can be read in and out of storage easily and in 1 tree.
 
-The 5 that are in the system should cover a lot of ground, anything trickier 
-should just be implemented as it's own Converter, ensuring that it responds to
-`#do_import(data)` and `#do_export(data)`.  
+### Basic Procs
+Each converter is really just a thin wrapper around a pair of procs (or other
+object that responds to .call(data).
+
+Each proc takes data, and when called, converts that data into something else
+
+#### StandardProcs.noop
+The noop proc simply returns the value passed to it. 
+`# proc{|data| data}` 
+
+#### StandardProcs.default(default_value)
+The default proc provides a default value if data is falsey.
+`StandardProcs.default(:default_value) # proc{|data| data || :default_value }
+
+#### StandardProcs.call_on_self(method_name)
+The call_on_self proc calls method_name on data.
+`StandardProcs.call_on_self(:intern) # proc{|data| data.send(:intern) }`
+`StandardProcs.call_on_self(:intern) # proc{|data| data.send(:to_s) }`
+
+#### StandardProcs.call_on(klass, with_method: :new)
+The call_on proc uses data as params for a method call.
+`StandardProcs.call_on(Pathname) # proc{|data| Pathname.send(:new,data)}`
+`StandardProcs.call_on(URI, :parse) # proc{|data| URI.send(:parse,data)}`
+
+#### StandardProcs.map(&block)
+The map proc converts each element of Array(data) using block.
+`StandardProcs.map{|data| URI.send(:parse,data)}`
+
+#### StandardProcs.inject(memo_obj)(&block)
+The map proc converts each element of Array(data) uses a memo_obj using block.
+`StandardProcs.inject({}){|memo,data| memo[data.name] = data}`
+
+#### Custom
+A proc is very easy to create, creating simple procs to do various tasks can
+simply many complex tasks
+```ruby
+dt_proc       = proc{|data| Time.now()}
+uri_proc      = proc{|data| URI.parse(data)}
+uri_out_proc  = proc{|data| data.to_s }
+tag_proc      = proc{|data| data.split(/,/)
+tag_join_proc = proc{|data| data.join(',')}
+```
+
+## Basic Converters
+The converters provided by the Convert module use various of the StandardProcs
+to achieve commonly used patterns.  
 
-Most of the converters wil have a pair of optional arguments: import_method 
-(defaults to :new) and export_method (defaults to :export). Export is simple, 
-it's the method called on the object, objects created using Traitorous 
-automatically respond_to export.  set export_method to :to_s in order to convert
-your Pathname object into a string.  Set import_method to :parse, to create your
-object with URI.parse. This should provide a tremendous amount of versatility.
+The Converter itself is a simple object that takes an importer, and an optional
+exporter and the provides a thin wrapper for `.import(data)` and `.export(data)`
+
+### Convert.noop
+This is the default converter for trait,  both importer and exporter are 
+`StandardProcs.noop`.  The primary purpose of this is so that data that doesn't
+need conversion have a simple converter that conforms to the same API as other
+converters.
+
+### Convert.default(default_value)
+This provides a `StandardProcs.default(default_value)` importer, and a 
+`StandardProcs.noop` exporter.
+
+Currently there isn't a way to skip nil or empty values on export, and so I've
+never had to make a decision about a more complex `.export(data)` proc for this
+converter.  Changing the signature to `StandardProcs.default(default_value, :include_on_export)`
+or it's logical opposite.  But I'm not sure which default behaviour is better.
+
+### Convert.model(model_name, container = :scalar)
+This is a pure convenience method that provides simple Object instantiaion
+for single objects, arrays, and hash values.  container may be :scaler, :array,
+:hash.  The container simply does a `proc{|data| model_name.new(data)}` on
+the single scalar, on each element of an array, or on each value of a hash.
 
 ```ruby
-# Example of using the defaults for IMport_method and export_method
-# import_method defaults to :new
-# export_method defaults to :export
-batman_data = {name: 'Batman', secret_identity: 'Bruce Wayne'}
-converter = Model.new(Superhero)
-superhero = converter.do_import(batman_data)
-# does this
-Superhero.send(import_method, data)
-# and is the same result as
-Superhero.new(batman_data)
-# exports by
-converter.do_export(superhero)
-# does this
-superhero.send(export_method)
-# and is the same result as
-superhero.export
-
-# Example of using a custom import_method and export_method
-batman_data_uri = '/batman/current'
-converter = Model.new(Superhero, import_method: :parse, export_method: :to_s)
-superhero = converter.do_import(batman_data)
-# does this
-uri = URI.send(import_method, batman_data)
-# and is the same result as
-URI.parse(batman_data)
-# exports by
-converter.do_export(uri)
-# does this
-uri.send(export_method)
-# and is the same result as
-uri.to_s
+# common uses
+Convert.model(Pathname) # Pathname.new(data)
+Convert.model(CustomClass, :array) # [CustomClass<#...>,CustomClass<#...>,...] 
+Convert.model(CustomClass, :hash) # {'orig_key_1' => CustomClass<#...>,'orig_key_2' => CustomClass<#...>...}
 ```
 
+### Convert.call_on_self(with_method, export_with: :itself)
+This provides an `StandardProcs.call_on_self(with_method)` importer and 
+`StandardProcs.call_on_self(export_with)` exporter
+
+Currently there is no way to pass additional arguments on the method call.  It
+should be easy enough to create a custom Converter if you need to do that.
+
+```ruby
+# common uses
+Convert.call_on_self(:intern, export_with: :to_s)
+Convert.call_on_self(:to_i)
+```
+
+### Convert.call_on(klass, with: :new, export_with: :export)
+This provides a `StandardProcs.call_on(klass, with_method: with)` importer
+and a `StandardProcs.call_on_self(:export)` exporter.
+
+Currently there is no way to pass additional arguments on the method call.  It
+should be easy enough to create a custom Converter if you need to do that.
+
+```
+# common uses
+c = Convert.call_on(Pathname) # Pathname.new(data)
+c = Convert.call_on(URI, :parse) # URI.parse(data)
+c = Convert.call_on(CustomClass, with: :import) # CustomClass.import(data)
+```
+
+### Convert.array(converter)
+
 ##### export
 My current design kind of places a lot of the responsibilities for the export
 sequence of the objects themselves.  And I'm both satisied with this design and 

data/VERSION

@@ -1 +1 @@
-0.6.1
+0.6.2

data/lib/traitorous.rb

@@ -45,7 +45,7 @@ module Traitorous
     #   be any object or module.
     #
     #   defaults to Traitorous::Converter::DEFAULT
-    def trait(attr_name, converter = Convert.skip)
+    def trait(attr_name, converter = Convert.noop)
       self.traits            ||= HASH.new
       self.traits[attr_name.intern] = converter
       attr_accessor attr_name

data/lib/traitorous/convert.rb

@@ -6,7 +6,7 @@ module Traitorous
       # .skip provides the simplest converter. It does nothing to the value
       #   except pass it through unchanged on both import and export
       # @return [Traitorous::Converter]
-      def skip
+      def noop
         Converter.new(
             StandardProcs.noop,
             StandardProcs.noop
@@ -25,7 +25,6 @@ module Traitorous
         )
       end
 
-
       # .call_on creates a StandardProc.call_on proc for the importer, and a
       #   StandardProc.call_on_self proc for the exporter.
       # @param method_name [Symbol, String] method to send data
@@ -39,13 +38,29 @@ module Traitorous
         )
       end
 
+      # .model(model_name) instantiates a model_name using model_name.new(data)
+      # @param model_name [Class,#new] the name of the model to be instantiated
+      # @return [Traitorous::Converter]
+      def model(model_name, container = :scalar)
+        case container
+          when :scalar
+            call_on(model_name)
+          when :array, []
+            self.array(self.call_on(model_name))
+          when :hash, {}
+            self.hash(self.call_on(model_name))
+          else
+            raise ArgumentError.new("No container of type: #{container}")
+        end
+      end
+
       # .call_on_self creates a StandardProc.call_on_self proc for the importer
       #   with the with_method param, and a StandardProc.call_on_self with the
       #   export_with param
       # @param with_method [Symbol, String] method to send data on import
       # @param export_with [Symbol, String] method to send data on export
       # @return [Traitorous::Converter]
-      def call_on_self(with_method, export_with: :export)
+      def call_on_self(with_method, export_with: :itself)
         Converter.new(
             StandardProcs.call_on_self(with_method),
             StandardProcs.call_on_self(export_with)
@@ -60,8 +75,8 @@ module Traitorous
       # @return [Traitorous::Converter]
       def array(converter)
         Converter.new(
-            proc { |data| Array(data).map { |entry| converter.importer.call(entry) } },
-            proc { |data| Array(data).map { |entry| converter.exporter.call(entry) } }
+            StandardProcs.map { |entry| converter.importer.call(entry) },
+            StandardProcs.map { |entry| converter.exporter.call(entry) }
         )
       end
 
@@ -71,8 +86,8 @@ module Traitorous
       # @return [Traitorous::Converter]
       def hash(value_converter)
         Converter.new(
-            proc { |data| data.inject({}) { |h, (k, v)| h[k] = value_converter.importer.call(v); h } },
-            proc { |data| data.inject({}) { |h, (k, v)| h[k] = value_converter.exporter.call(v); h } },
+            StandardProcs.inject({}) { |h, (k, v)| h[k] = value_converter.importer.call(v) },
+            StandardProcs.inject({}) { |h, (k, v)| h[k] = value_converter.exporter.call(v) },
         )
       end
 
@@ -90,13 +105,11 @@ module Traitorous
       # @return [Traitorous::Converter]
       def array_to_hash(key_converter, value_converter)
         Converter.new(
-            proc do |data_arr|
-              data_arr.inject({}) do |h, d|
-                v    = value_converter.importer.call(d)
-                k    = key_converter.importer.call(v)
-                h[k] = v
-                h
-              end
+            StandardProcs.inject({}) do |memo_obj, data|
+              value = value_converter.importer.call(data)
+              key = key_converter.importer.call(value, data)
+              memo_obj[key] = value
+              memo_obj
             end,
             proc { |data_hsh| data_hsh.values.map { |value| value_converter.exporter.call(value) } }
         )

data/lib/traitorous/standard_procs.rb

@@ -12,14 +12,14 @@ module Traitorous
       #   otherwise it returns it's default value
       # @param default_value [Object] the default value to use with data is
       #   falsey
-      # @return [Object] returns data || default_value
+      # @return [Proc]
       def default(default_value)
         proc { |data| data || default_value }
       end
 
       # This proc calls method_name on data.
       # @param method_name [Symbol, String] method to send data
-      # @return [Object] result of calling method_name on data
+      # @return [Proc]
       def call_on_self(method_name)
         proc { |data| data.send(method_name) }
       end
@@ -27,8 +27,32 @@ module Traitorous
       # This proc calls klass with :with and passes data as params
       # @param klass [Class, Module, Object] obj to call
       # @param with_method: [Symbol, String] method to send klass with data as params
+      # @return [Proc]
       def call_on(klass, with_method: :new)
-        proc {|data| klass.send(with_method, data)}
+        proc { |data| klass.send(with_method, data) }
+      end
+
+      # This proc calls map on data, and calls the block for each element.
+      # @param block [Class, Module, Object] obj to call
+      # @return [Proc]
+      def map(&block)
+        raise ArgumentError.new("Must be called with block") unless block_given?
+        proc { |data_arr| Array(data_arr).map { |data| block.call(data) } }
+      end
+
+      # This proc calls map on data, and calls the block for each element.
+      # @param memo_obj [Array,Hash,#dup] dup called on this and used as the
+      #   seed object for the inject call.
+      # @param block [Class, Module, Object] obj to call
+      # @return [Proc]
+      def inject(memo_obj, &block)
+        raise ArgumentError.new("Must be called with block") unless block_given?
+        proc do |data_arr|
+          Array(data_arr).inject(memo_obj.dup) do |memo_obj, data|
+            block.call(memo_obj, data)
+            memo_obj
+          end
+        end
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: traitorous
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.2
 platform: ruby
 authors:
 - scott m parrish
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-10-10 00:00:00.000000000 Z
+date: 2015-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport