Merge pull request #12 from Sage/feature_attribute_alias

Added attribute name alias functionality

Author: vaughanbrittonsage

README.md

@@ -49,6 +49,26 @@ Or install it yourself as:
 
 ClassKit entities can be created by implementing the `extend ClassKit` extend into the entity class and then using the `attr_accessor_type` method to register attributes as above inplace of the standard ruby `attr_accessor` method.
 
+ClassKit entity attributes can use a name alias in order to parse to/from hashes/json with different key names, see the example below:
+
+    class Address
+        extend ClassKit   
+             
+        attr_accessor_type :line1, type: String, alias_name: :l1
+        attr_accessor_type :line2, alias_name: :l2
+        attr_accessor_type :postcode, alias_name: :pc
+    end
+    
+    { "l1": "23 the street", "l2": "the town", "pc": "ne1 4rt" }
+
+To use alias names you must specify `use_alias = true` for the following helper methods:
+
+    helper.to_hash(entity, true)
+    helper.from_hash(hash: hash_object, klass: entity_klass, use_alias: true)
+    
+    helper.to_json(entity, true)
+    helper.from_json(json: json_string, klass: entity_klass, use_alias: true)
+
 ### attr_accessor_type
 
 This method is used to add typed attributes to a class.
@@ -111,12 +131,13 @@ Example:
 
     helper.is_class_kit?(obj)
 
-#### #to_hash(object)
+#### #to_hash(object, use_alias)
 
 This method is called to convert a ClassKit entity into a `Hash`.
 
 [Params]
-- `object` This is the ClassKit entity to convert.
+- `object` [Required] This is the ClassKit entity to convert.
+- `use_alias` [Optional] [Default=false] This is used to specify if attribute alias names should be used.
 
 [Return]
 
@@ -126,14 +147,15 @@ Example:
 
     hash = helper.to_hash(obj)
         
-#### #from_hash(hash:,klass:)
+#### #from_hash(hash:,klass:, use_alias:)
 
 This method is called to convert a `Hash` into a ClassKit entity.
 
 [Params]
-- `hash:` This is the `Hash` to convert.
-- `klass:` This is the class of the ClassKit entity you want to convert the `Hash` into. 
-(NOTE: It should be the fully qualified class name including modules)
+- `hash:` [Required] This is the `Hash` to convert.
+- `klass:` [Required] This is the class of the ClassKit entity you want to convert the `Hash` into. 
+> NOTE: It should be the fully qualified class name including modules
+- `use_alias` [Optional] [Default=false] This is used to specify if attribute alias names should be used.
 
 [Return]
 
@@ -143,12 +165,13 @@ Example:
 
     entity = helper.from_hash(hash: hsh, klass: Contact)
 
-#### #to_json(object)
+#### #to_json(object, use_alias)
 
 This method is called to convert a ClassKit entity into JSON.
 
 [Params]
 - `object` This is the ClassKit entity to convert.
+- `use_alias` [Optional] [Default=false] This is used to specify if attribute alias names should be used.
 
 [Return]
 
@@ -158,14 +181,15 @@ Example:
 
     json_string = helper.to_json(obj)
 
-#### #from_json(json:, klass:)
+#### #from_json(json:, klass:, use_alias:)
 
 This method is called to convert a JSON string into a ClassKit entity.
 
 [Params]
 - `json:` This is the JSON string to convert.
 - `klass:` This is the class of the ClassKit entity you want to convert the JSON into.
-(NOTE: It should be the fully qualified class name including modules)
+> NOTE: It should be the fully qualified class name including modules
+- `use_alias` [Optional] [Default=false] This is used to specify if attribute alias names should be used.
 
 [Return]
 

lib/class_kit/class_methods.rb

@@ -1,15 +1,29 @@
 module ClassKit
-  def attr_accessor_type(name, type: nil, collection_type: nil, allow_nil: true, default: nil, auto_init: false,
-                         meta: {})
-
+  def attr_accessor_type(
+    name,
+    type: nil,
+    collection_type: nil,
+    allow_nil: true,
+    default: nil,
+    auto_init: false,
+    alias_name: nil,
+    meta: {})
     unless instance_variable_defined?(:@class_kit_attributes)
       instance_variable_set(:@class_kit_attributes, {})
     end
 
     attributes = instance_variable_get(:@class_kit_attributes)
 
-    attributes[name] = { name: name, type: type, collection_type: collection_type, allow_nil: allow_nil,
-                         default: default, auto_init: auto_init, meta: meta }
+    attributes[name] = {
+      name: name,
+      type: type,
+      collection_type: collection_type,
+      allow_nil: allow_nil,
+      default: default,
+      auto_init: auto_init,
+      alias: alias_name,
+      meta: meta
+    }
 
     class_eval do
       define_method name do

lib/class_kit/helper.rb

@@ -16,17 +16,17 @@ def validate_class_kit(klass)
                                     "Class: #{klass} does not implement ClassKit.")
     end
 
-    #This method is called to convert a ClassKit object into a Hash.
-    def to_hash(object)
+    # This method is called to convert a ClassKit object into a Hash.
+    def to_hash(object, use_alias = false)
       validate_class_kit(object.class)
 
       hash = {}
 
       attributes = @attribute_helper.get_attributes(object.class)
       attributes.each do |attribute|
-        key = attribute[:name]
+        key = use_alias ? (attribute[:alias] || attribute[:name]) : attribute[:name]
         type = attribute[:type]
-        value = object.public_send(key)
+        value = object.public_send(attribute[:name])
         if value != nil
           hash[key] = if is_class_kit?(type)
                         to_hash(value)
@@ -47,18 +47,18 @@ def to_hash(object)
       hash
     end
 
-    #This method is called to convert a Hash into a ClassKit object.
-    def from_hash(hash:, klass:)
+    # This method is called to convert a Hash into a ClassKit object.
+    def from_hash(hash:, klass:, use_alias: false)
       validate_class_kit(klass)
 
       @hash_helper.indifferent!(hash)
       entity = klass.new
       attributes = @attribute_helper.get_attributes(klass)
       attributes.each do |attribute|
-        key = attribute[:name]
+        key = use_alias ? (attribute[:alias] || attribute[:name]) : attribute[:name]
         type = attribute[:type]
 
-        #if the hash value is nil skip it
+        # if the hash value is nil skip it
         next if hash[key].nil?
 
         value = if is_class_kit?(type)
@@ -79,22 +79,22 @@ def from_hash(hash:, klass:)
                   hash[key]
                 end
 
-        entity.public_send(:"#{key}=", value)
+        entity.public_send(:"#{attribute[:name]}=", value)
       end
 
       entity
     end
 
-    #This method is called to convert a ClassKit object into JSON.
-    def to_json(object)
-      hash = to_hash(object)
+    # This method is called to convert a ClassKit object into JSON.
+    def to_json(object, use_alias = false)
+      hash = to_hash(object, use_alias)
       JSON.dump(hash)
     end
 
-    #This method is called to convert JSON into a ClassKit object.
-    def from_json(json:, klass:)
+    # This method is called to convert JSON into a ClassKit object.
+    def from_json(json:, klass:, use_alias: false)
       hash = JSON.load(json)
-      from_hash(hash: hash, klass: klass)
+      from_hash(hash: hash, klass: klass, use_alias: use_alias)
     end
   end
 end

spec/class_kit/helper_spec.rb

@@ -31,6 +31,23 @@
         expect(hash[:country]).to eq(entity.country)
       end
     end
+    context 'when a valid class is specified with json aliases' do
+      let(:entity) do
+        TestAddressWithAlias.new.tap do |e|
+          e.line1 = 'line1'
+          e.line2 = 'line2'
+          e.postcode = 'ne1 8rt'
+        end
+      end
+      it 'should return a hash' do
+        hash = subject.to_hash(entity, true)
+        expect(hash).to be_a(Hash)
+        expect(hash[:l1]).to eq(entity.line1)
+        expect(hash[:l2]).to eq(entity.line2)
+        expect(hash[:pc]).to eq(entity.postcode)
+        expect(hash[:c]).to eq(entity.country)
+      end
+    end
     context 'when a valid class is specified with array attributes' do
       let(:address1) do
         TestAddress.new.tap do |e|
@@ -134,6 +151,24 @@
         expect(entity.address_collection.length).to eq(0)
       end
     end
+    context 'when a valid hash is specified with aliases' do
+      let(:hash) do
+        {
+          l1: 'line1',
+          l2: 'line2',
+          pc: 'ne1 4rt',
+          c: 'United Kingdom'
+        }
+      end
+      it 'should convert the hash' do
+        entity = subject.from_hash(hash: hash, klass: TestAddressWithAlias, use_alias: true)
+        expect(entity).not_to be_nil
+        expect(entity.line1).to eq hash[:l1]
+        expect(entity.line2).to eq hash[:l2]
+        expect(entity.postcode).to eq hash[:pc]
+        expect(entity.country).to eq hash[:c]
+      end
+    end
   end
 
   describe '#to_json' do
@@ -195,6 +230,24 @@
       expect(result_hash['address_collection'].length).to eq(2)
       expect(result_hash['address_collection'][0]['post_code']).to eq hash[:address_collection][0][:post_code]
     end
+    context 'when entity specifies aliases' do
+      let(:address) do
+        TestAddressWithAlias.new.tap do |a|
+          a.line1 = 'street 1'
+          a.line2 = 'street 2'
+          a.postcode = 'ne3 5rt'
+        end
+      end
+      it 'converts class to json using aliases' do
+        result = subject.to_json(address, true)
+        expect(result).to be_a(String)
+        result_hash = JSON.load(result)
+        expect(result_hash['l1']).to eq address.line1
+        expect(result_hash['l2']).to eq address.line2
+        expect(result_hash['pc']).to eq address.postcode
+        expect(result_hash['c']).to eq address.country
+      end
+    end
   end
 
   describe '#from_json' do
@@ -253,5 +306,22 @@
       expect(entity.address_collection[1].line2).to eq(hash[:address_collection][1][:line2])
       expect(entity.address_collection[1].postcode).to eq(hash[:address_collection][1][:postcode])
     end
+    context 'when entity has json aliases' do
+      let(:hash) do
+        {
+          l1: 'line1',
+          l2: 'line2',
+          pc: 'ne1 4rt',
+          c: 'United Kingdom'
+        }
+      end
+      it 'converts json into the relevant entity' do
+        entity = subject.from_json(json: json, klass: TestAddressWithAlias, use_alias: true)
+        expect(entity.line1).to eq(hash[:l1])
+        expect(entity.line2).to eq(hash[:l2])
+        expect(entity.postcode).to eq(hash[:pc])
+        expect(entity.country).to eq(hash[:c])
+      end
+    end
   end
-end
+end

spec/class_kit/test_objects.rb

@@ -6,6 +6,14 @@ class TestAddress
   attr_accessor_type :country, type: String, default: 'United Kingdom'
 end
 
+class TestAddressWithAlias
+  extend ClassKit
+  attr_accessor_type :line1, type: String, alias_name: :l1
+  attr_accessor_type :line2, alias_name: :l2
+  attr_accessor_type :postcode, alias_name: :pc
+  attr_accessor_type :country, type: String, default: 'United Kingdom', alias_name: :c
+end
+
 class TestEntity
   extend ClassKit