traitorous 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0597d522d23bd2c71b7f3c32c4ba7051354855e9
-  data.tar.gz: 74bafa4cbd011ab8ab2e337a12d7f5c2294288b0
+  metadata.gz: 51c87b262becc747a334dce20c4b0f149de698d4
+  data.tar.gz: 384664790edbfbbcbc95043b7f4cc3fbe78c78e0
 SHA512:
-  metadata.gz: 4fd180776568fd37efb6663e4f2dc0635e58973dcd55d7803c7cec0680de77b50b811802897b1ae2e26a855727cfc7d513f764c2aeefd42b35f08f5ad864c685
-  data.tar.gz: c891627cf1985ec7be19f239c81d9e78bb99c5648678fffe063c9c1f26599d5aa9315f8f29766107a4a1bf6aba305f2a5434eafe74ec1b065663894b5c30cf96
+  metadata.gz: 27cecb8725cfe6914c81e26ae45cc2e5f9669228e01f3c139d4e02a309af4763918c45a22e75bd9453b9fbd8254c70248ed3f0ed4a0c7eb5e10e9626cedd47ba
+  data.tar.gz: 052ece595a8928766a34eaede53b690981834db33cbedeb2215f940e3d354d2b165118e7e3a2403ff179ecc7d538103c7edf0aa8f645539269c13825627b841e

data/README.md

@@ -1,7 +1,8 @@
-# Traitorous
+# Traitorous [![Gem Version](https://badge.fury.io/rb/traitorous.svg)](http://badge.fury.io/rb/traitorous)
 
 [![Build Status](https://travis-ci.org/anithri/traitorous.svg)](https://travis-ci.org/anithri/traitorous)
 [![Code Climate](https://codeclimate.com/github/anithri/traitorous/badges/gpa.svg)](https://codeclimate.com/github/anithri/traitorous)
+[![Inline docs](http://inch-ci.org/github/anithri/traitorous.svg?branch=master)](http://inch-ci.org/github/anithri/traitorous)
 
 This is a simple trait based system that emphasizes reading in and out data 
 structures, using an plugin Converter system.  Each trait defined has a 
@@ -85,6 +86,18 @@ puts Area.new(area.export) == area
 # true
 ```
 
+## Roadmap
+
+1.  Add better documentation
+2.  better testing of deep constructions
+3.  Additional Converters
+    a. DefaultValueDynamic that stores code to run upon input or output
+    b. VariableArray that uses a sub-type in the opts to location the correct
+       class to instantiate instead of always using a uniform class
+    c. Validations?
+    d. translations?
+    e. class specific (Date, CreditCard)
+
 ## Development
 
 I use Guard to automate testing.  It won't affect anything execpt the disk space

data/Rakefile

@@ -1,9 +1,10 @@
 require 'bundler/gem_tasks'
-#require 'rake/version_task'
+require 'rake/version_task'
 require 'rspec/core/rake_task'
 
-#Rake::VersionTask.new
-
+Rake::VersionTask.new do |task|
+  task.with_git_tag = true
+end
 RSpec::Core::RakeTask.new(:spec)
 
 task :default  => :spec

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/traitorous/converter/identity.rb

@@ -1,10 +1,32 @@
 module Traitorous
   module Converter
+    # The Identity converter is used as a simple default which performs the
+    # jobs of a Converter without changing the inputs at all.
+    #
+    # This converter can be used when you have simple data (strings, dates,
+    #   numbers, hashes and arrays of the same) that doesn't need to be inflated
+    #   into an object and needs no changes to be safely stored as the same.
     class Identity
+      # do_export is called in order to take an existing piece of data and
+      #   prepare it to be written to a simpler data structure.
+      #
+      # The Identity converter exports the same data it is passed without
+      #   changing them at all.
+      #
+      # @params data [Object] the data object passed in to be exported
+      # @return [Object] exports data to a form simple enough to save as JSON
       def do_export(data)
         data
       end
 
+      # do_import is called in order to take some opts and to turn them into
+      #   instantiated objects, arrays, or other types of transformation
+      #
+      # The Identity converter imports the same opts it is passed without
+      #   changing them at all.
+      #
+      # @params opts [Object] the options to be imported
+      # @return [Object] opts
       def do_import(opts)
         opts
       end

data/lib/traitorous/converter/method_keyed_uniform_hash.rb

@@ -0,0 +1,43 @@
+module Traitorous
+  module Converter
+    # MethodKeyedUniformedHash is meant to take an array of a simple data
+    #   structures and convert each into a uniform class, and then will call a
+    #   key_method on that class and use it as the key in the returned hash.
+    #
+    # Exported data will be converted into an array calling do_export on each
+    #   element
+    class MethodKeyedUniformHash
+      attr_accessor :key_method, :uniform_class
+      # @param key_method [Symbol] the method to call on the uniform_class instance
+      #   to generate the key in the returned hash
+      # @param uniform_class [Class, #new] the class to instantiate with each
+      #   element of the do_import array
+      def initialize(key_method, uniform_class)
+        @key_method = key_method
+        @uniform_class = uniform_class
+      end
+
+      # The import instantiates each element of the array as an instance of
+      #   the uniform_class, the key is determined by calling key_method on the
+      #   instance and then they are joined to the result hash as a key,
+      #   instance pair.
+      # @param arr_data [Array] the array of data to instantiate
+      # @return [Hash] hash containing key, instance pairs
+      def do_import(arr_data)
+        out = {}
+        arr_data.each do |elem_data|
+          obj = uniform_class.new(elem_data)
+          out[obj.send(key_method)] = obj
+        end
+        out
+      end
+
+      # @param hsh_data [Hash<obj,#export>] keys are ignored
+      # @return Array each element of the values of hsh_data has #export called
+      #   on it.
+      def do_export(hsh_data)
+        hsh_data.values.map{|instance| instance.export }
+      end
+    end
+  end
+end

data/lib/traitorous/converter/model.rb

@@ -1,16 +1,39 @@
 module Traitorous
   module Converter
+    # The Model converter is used a a simple way to instantiate an object from
+    #   the model_class using the imported opts, and which will call .export on
+    #   the data.
+    #
+    # This converter can be used when you have a set of opts that you can pass
+    #   to a classes .new command in order to instantiate an object.
     class Model
+      # @param model_klass [Class,#new] class to instantiate when importing
       def initialize(model_klass)
         @model_klass = model_klass
       end
-      def do_import(opts)
-        @model_klass.new(opts)
-      end
+
+      # do_export is called in order to take an existing piece of data and
+      #   prepare it to be written to a simpler data structure.
+      #
+      # The model converter exports the data by calling .export on it
+      #
+      # @params data [Object] the data object passed in to be exported
+      # @return [Object] result of data.export
       def do_export(data)
         data.export
       end
 
+      # do_import is called in order to take some opts and to turn them into
+      #   instantiated objects, arrays, or other types of transformation
+      #
+      # The model converter imports the opts by instantiating a model_class
+      #   object with it.
+      #
+      # @params opts [Object] the options to be exported
+      # @return [Object] result of model_klass.new(opts)
+      def do_import(opts)
+        @model_klass.new(opts)
+      end
     end
   end
 end

data/lib/traitorous/equality.rb

@@ -1,7 +1,31 @@
 require 'traitorous'
 module Traitorous
+  # Provides a mechanism to test equality of objects that implement a traits hash.
+  # This is an iffy concept, and if I didn't happen to be using a Coordinate
+  # object in te project this was extracted from it probably wouldn't be a part
+  #
+  # For this module to work it makes a set of assumptions.
+  # 1. The base assumption of the types of objects created using Traitorous is
+  #    that they are easily expressed in text.
+  # 2. That the aggregate of the traits equality means the 2 are equal
+  # 3. If a trait is an Array, each element of the array is tested against the 2nd,
+  #    and vice versa.
+  # 4. all other equality is tested using ==
+  # 5. nested objects should also implement equality to facilitate the
+  #    comparisons of deeply nested structures
+  #
+  # Further expansions might call for the converter to assume an equality guise
   module Equality
+
+    # Override the normal :== method to compare each trait individually when
+    # testing equality.
+    #
+    # Coordinate.new(x: 1, y: 2) == Coordinate.new(x:1, y: 2)
+
+    # @param other_val [#traits] target of comparison
+    # @return Boolean if all traits values match return true.
     def ==(other_val)
+      return false unless self.class == other_val.class
       traits.keys.all? do |trait_name|
         orig_trait  =      self.send(trait_name.intern)
         other_trait = other_val.send(trait_name.intern)
@@ -9,6 +33,12 @@ module Traitorous
       end
     end
 
+    # compare the equality of 2 arrays, and I'm not sure this is the best way to
+    # do the comparisons.
+    # @params alpha [Array] first array
+    # @params beta [Array] second array
+    # @return [Boolean] true if every element in 1 array is equal(==) to an
+    #   element in the 2nd and vice versa (order doesn't matter, should it?)
     def array_equality(alpha, beta)
       return false unless (alpha.is_a?(Array) && beta.is_a?(Array))
       alpha.all?{|a| beta.any?{|b| a == b}}

data/lib/traitorous.rb

@@ -1,18 +1,38 @@
 require 'active_support/core_ext/hash/indifferent_access'
 
 module Traitorous
+
+  # Use the HashWithIndifferentAccess from the activesupport gem.
   HASH = HashWithIndifferentAccess
 
+  # Read the VERSION file in gem root to set version number.
   VERSION = File.read('VERSION')
 
+  # The converter namespace is used to store Converter classes.
+  # Each Converter may take initializer arguments,  to allow specific classes or
+  # values to be defined, and 2 methods: :do_import and :do_export.
+  # do_import is meant to take the data, and use the initial data to combine to
+  # build objects or other data structures.
   module Converter
+    # The purpose of the converters are to facilitate the importation of simple
+    #   JSON or YAML data and import that data into an arbitrarily nested tree
+    #   of objects.  And then to take those object and be able to export that data
+    #   in a simple form ready to save.
+    #   opts = {some: 'deep', data: ['structures']}
+    #    r = Mission.new(opts)
+    #    Mission.new(r.export) == r
     require 'traitorous/converter/identity'
     require 'traitorous/converter/default_value_static'
     require 'traitorous/converter/model'
     require 'traitorous/converter/uniform_array'
+    require 'traitorous/converter/method_keyed_uniform_hash'
+    # if no other converter is declared, use the identity converter which
+    # merely pass through the data passed to it.
     DEFAULT_CONVERTER = Converter::Identity.new
   end
+
   require 'traitorous/equality'
+
   module ClassMethods
     attr_accessor :traits
 
@@ -30,6 +50,7 @@ module Traitorous
   end
 
   def initialize(opts = {})
+    raise "No traits have been defined for #{self.class}" unless self.class.traits
     @opts = HASH.new(opts)
     traits.each_pair do |new_trait, trait_opts|
       converter = trait_opts[:converter]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: traitorous
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - scott m parrish
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-09-01 00:00:00.000000000 Z
+date: 2015-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -104,6 +104,7 @@ files:
 - lib/traitorous.rb
 - lib/traitorous/converter/default_value_static.rb
 - lib/traitorous/converter/identity.rb
+- lib/traitorous/converter/method_keyed_uniform_hash.rb
 - lib/traitorous/converter/model.rb
 - lib/traitorous/converter/uniform_array.rb
 - lib/traitorous/equality.rb