jsoning 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3fd493cccd6b9c1cfb0d8db8dd60cd9a6b61e8b9
-  data.tar.gz: 90afc5cd5c89dd9ae57ff0eb68059454aecfec28
+  metadata.gz: 69a10f48340146f1c819bd5d038088913fdd63e8
+  data.tar.gz: d5761009f4937cf74743679b48ffdd471bfbf3dc
 SHA512:
-  metadata.gz: 979a26bc4aadde42006c99ed4b1b137e36c1c24a1efe6f400cca71708f695ac37395630c84ebbb4bb412a28245fc1056f34b377503ad4ea04da44aa3ab4c64db
-  data.tar.gz: 48e6a895798ecd4d255f632c669d366d26dca4d954f3dcfd1906e45da69783de43ca0f7c59e0dd0a61316d94fa253dbfb5f32f3337c45ef2f709d943806dd60d
+  metadata.gz: 6e6edba66976d8f2056c307ccb774f97259db82d3801eadb7c4540792a6e3a09d53327437c9b0fe83b1ec829d936d7b43efd4cb9d9a60deea1059398ec2f5f53
+  data.tar.gz: a36e4c08c15083b79387d72b7f2c0b2aa116e4b3c87ab0944ebfc31ce7c600c5c4347117fd7e8811e06e2dd39241b2f8d883a1ffe5cb3deaeaa2b65d361fb88d

data/README.md

@@ -7,6 +7,8 @@ any Ruby object there is. Kiss good bye to complexity
 [![Code Climate](https://codeclimate.com/github/saveav/jsoning/badges/gpa.svg)](https://codeclimate.com/github/saveav/jsoning)
 [ ![Codeship Status for saveav/bali](https://codeship.com/projects/b58d3950-493b-0133-a217-168d58eb1296/status?branch=release)](https://codeship.com/projects/105558)
 
+Please refer to the test spec for better understanding. Thank you.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -248,6 +250,51 @@ Calling: `Jsoning.parse(the_json_string, My::User)` will yield a Hash as follow:
  "registered_at"=>"2015-11-01T14:41:09+00:00"}
 ```
 
+## Versioning
+
+Since beginning, JSONing is made to easy serializing/deserializing data from API call.
+Often, API call itself can be versioned. Therefore, it would be better if JSONing
+also support versioning, which it does!
+
+By default, though, all schema are under default version. Version will be altered when
+specifically modified by `version` modifier.
+
+Suppose we have our `My::Book` to be versioned:
+
+```ruby
+Jsoning.for(My::Book) do
+  version :v1 do
+    key :name
+  end
+  version :v2 do
+    key :book_name, from: :name
+  end
+end
+```
+
+At this point, ignoring that we have ever defined `My::Book` before, `My::Book` will have
+2 Jsoning versions. If we take into account the fact that we have defined `My::Book` previously,
+then, we will have one additional version: the default version.
+
+Spec below will pass:
+
+```ruby
+book = My::Book.new("Harry Potter")
+expect(Jsoning.generate(book, hash: true, version: :v1)).to eq({"name"=>"Harry Potter"})
+expect(Jsoning.generate(book, hash: true, version: :v2)).to eq({"book_name"=>"Harry Potter"})
+```
+
+We can also generate the whole user json/hash, too:
+
+```ruby
+json = Jsoning.generate(user, version: :v1)
+expect(JSON.parse(json)).to eq({"name"=>"Adam Baihaqi", "years_old"=>21, "gender"=>"male", "books"=>[{"name"=>"Quiet: The Power of Introvert"}, {"name"=>"Harry Potter and the Half-Blood Prince"}], "degree_detail"=>nil, "registered_at"=>"2015-11-01T14:41:09+0000"})
+json = Jsoning.generate(user, version: :v2)
+expect(JSON.parse(json)).to eq({"name"=>"Adam Baihaqi", "years_old"=>21, "gender"=>"male", "books"=>[{"book_name"=>"Quiet: The Power of Introvert"}, {"book_name"=>"Harry Potter and the Half-Blood Prince"}], "degree_detail"=>nil, "registered_at"=>"2015-11-01T14:41:09+0000"})
+```
+
+If for when generating object, the requested versioning is undefined, the default version will be used.
+
 ## Changelog
 
 == Version 0.1.0
@@ -274,6 +321,10 @@ Calling: `Jsoning.parse(the_json_string, My::User)` will yield a Hash as follow:
    raised due to Jsoning does not know how to extract value from them. However, if the object
    is converted to JSON string, everything is working as expected.
 
+== Version 0.6.0
+
+1. Versioning the way JSON/Hash is de-serialized/serialized
+
 ## License
 
 The gem is proudly available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/lib/jsoning/dsl/for_dsl.rb

@@ -1,10 +1,28 @@
 class Jsoning::ForDsl
   attr_reader :protocol
+  attr_accessor :current_version_object
+  @@mutex = Mutex.new
 
   def initialize(protocol)
     @protocol = protocol
   end
 
+  # specify the version under which key will be executed
+  def version(version_name)
+    @@mutex.synchronize do
+      # todo: make sure version cannot be nester, in order that to be possible
+      # version must have its own dsl, dduh
+      # fail Jsoning::Error, "Version cannot be nested" if current_version_object
+
+      # retrieve the version, or create a new one if not yet defined
+      version = protocol.get_version(version_name)
+      version = protocol.add_version(version_name) if version.nil?
+
+      self.current_version_object = version
+      yield
+    end
+  end
+
   # args is first specifying the name for variable to be displayed in JSON docs,
   # and then the options. options are optional, if set, it can contains:
   # - from
@@ -23,7 +41,14 @@ class Jsoning::ForDsl
       end
     end
 
-    mapper = Jsoning::Mapper.new
+    # get the version instance
+    version_instance = if self.current_version_object.nil?
+      protocol.get_version!(:default)
+    else
+      current_version_object
+    end 
+
+    mapper = Jsoning::Mapper.new(version_instance)
     if block_given?
       raise Jsoning::Error, "Cannot parse block to key"
     else
@@ -38,6 +63,7 @@ class Jsoning::ForDsl
 
     options.keys { |key| raise Jsoning::Error, "Undefined option: #{key}" }
 
-    protocol.add_mapper mapper
+    # add mapper to the version
+    version_instance.add_mapper(mapper)
   end
 end

data/lib/jsoning/foundations/mapper.rb

@@ -1,5 +1,8 @@
 # responsible of mapping from object to representable values, one field at a time
 class Jsoning::Mapper
+  # access to a version instance
+  attr_accessor :version
+
   # when mapped, what will be the mapped name
   attr_writer :name
 
@@ -9,10 +12,11 @@ class Jsoning::Mapper
   attr_accessor :parallel_variable
   attr_accessor :custom_block
 
-  def initialize
+  def initialize(version_instance)
     self.parallel_variable = nil
     @default_value = nil
     self.nullable = true
+    self.version = version_instance
   end
 
   def nullable?
@@ -30,29 +34,29 @@ class Jsoning::Mapper
   end
 
   # map this very specific object's field to target_hash
-  def extract(object, target_hash)
+  def extract(object, requested_version_name, target_hash)
     target_value = nil
 
     if object.respond_to?(parallel_variable)
       parallel_val = object.send(parallel_variable)
-      target_value = deep_parse(parallel_val)
+      target_value = deep_parse(parallel_val, requested_version_name)
     end
 
     if target_value.nil?
-      target_value = self.default_value
+      target_value = self.default_value(requested_version_name)
       if target_value.nil? && !self.nullable?
         raise Jsoning::Error, "Null value given for '#{name}' when serializing #{object}"
       end
     end
-    target_hash[name] = deep_parse(target_value)
+    target_hash[name] = deep_parse(target_value, requested_version_name)
   end
 
-  def default_value
+  def default_value(version_name = self.version.version_name)
     if @default_value
       if @default_value.is_a?(Proc)
-        return deep_parse(@default_value.())
+        return deep_parse(@default_value.(), version_name)
       else
-        return deep_parse(@default_value)
+        return deep_parse(@default_value, version_name)
       end
     else
       nil
@@ -60,7 +64,7 @@ class Jsoning::Mapper
   end
 
   private
-    def deep_parse(object)
+    def deep_parse(object, version_name)
       parsed_data = nil
 
       value_extractor = Jsoning::TYPE_EXTENSIONS[object.class.to_s]
@@ -70,19 +74,19 @@ class Jsoning::Mapper
         if object.is_a?(Array)
           parsed_data = []
           object.each do |each_obj|
-            parsed_data << deep_parse(each_obj)
+            parsed_data << deep_parse(each_obj, version_name)
           end
         elsif object.is_a?(Hash)
           parsed_data = {}
           object.each do |obj_key_name, obj_val|
-            parsed_data[obj_key_name] = deep_parse(obj_val)
+            parsed_data[obj_key_name] = deep_parse(obj_val, version_name)
           end
         elsif object.is_a?(Integer) || object.is_a?(Float) || object.is_a?(String) ||
           object.is_a?(TrueClass) || object.is_a?(FalseClass) || object.is_a?(NilClass)
           parsed_data = object
         else
           protocol = Jsoning.protocol_for!(object.class)
-          parsed_data = protocol.retrieve_values_from(object)
+          parsed_data = protocol.retrieve_values_from(object, {version: version_name})
         end
       end
 

data/lib/jsoning/foundations/protocol.rb

@@ -1,68 +1,77 @@
 # takes care of the class
 class Jsoning::Protocol
   attr_reader :klass
-  attr_reader :mappers
-  attr_reader :mappers_order
+  attr_reader :version_instances
 
   def initialize(klass)
     @klass = klass
+    @version_instances = {}
 
-    # mappers, only storing symbol of mapped values
-    @mappers_order = []
+    # each protocol has a default version named :default
+    add_version(:default)
 
-    @mappers = {}
+    self
   end
 
-  def add_mapper(mapper)
-    raise Jsoning::Error, "Mapper must be of class Jsoning::Mapper" unless mapper.is_a?(Jsoning::Mapper)
-    @mappers_order << canonical_name(mapper.name)
-    @mappers[canonical_name(mapper.name)] = mapper
+  # add a new version, a protocol can handle many version
+  # to export the JSON
+  def add_version(version_name)
+    unless version_name.is_a?(String) || version_name.is_a?(Symbol)
+      fail "Version name must be either a String or a Symbol"
+    end
+    version = Jsoning::Version.new(self)
+    version.version_name = version_name
+    @version_instances[version.version_name] = version
+    version
   end
 
-  def mapper_for(name)
-    @mappers[canonical_name(name)]
+  # retrieve a defined version, or return nil if undefined
+  def get_version(version_name)
+    @version_instances[version_name.to_s]
   end
 
-  # generate a JSON object
-  # options:
-  # - pretty: pretty print json data
-  def generate(object, options = {})
-    pretty = options[:pretty]
-    pretty = options["pretty"] if pretty.nil?
-    pretty = false if pretty.nil?
-
-    data = retrieve_values_from(object)
-
-    if pretty
-      JSON.pretty_generate(data)
-    else
-      JSON.generate(data)
-    end
+  # retrieve a defined version, or fail if undefined
+  def get_version!(version_name)
+    version = get_version(version_name)
+    fail Jsoning::Error, "Unknown version: #{version_name}" if version.nil?
+    version
   end
 
   # construct the JSON from given object
-  def retrieve_values_from(object)
+  # options:
+  #  - version: the version to be used for processing 
+  def retrieve_values_from(object, options)
+    # user will pass in version, rather than version_name, although actually
+    # it is a version_name instead of version instance
+    version_name = options[:version]
+    # use default if version is undefined
+    version = get_version(version_name) || get_version(:default)
+
     # hold data here
     data = {}
 
-    mappers_order.each do |mapper_sym|
-      mapper = mapper_for(mapper_sym)
-      mapper.extract(object, data)
+    version.mappers_order.each do |mapper_sym|
+      mapper = version.mapper_for(mapper_sym)
+      # version_name and version may be different, that is when the user uses version
+      # that is not yet defined, therefore, will fall to default. therefore, user
+      # version_name as this is what is requested by the caller
+      mapper.extract(object, version_name, data)
     end
 
     data
   end
 
   # construct hash from given JSON
-  def construct_hash_from(json_string)
+  def construct_hash_from(json_string, version_name)
     data = {}
 
     # make all json obj keys to downcase, symbol
     json_obj = JSON.parse(json_string)
     json_obj = Hash[json_obj.map { |k, v| [k.to_s.downcase, v]}]
 
-    mappers_order.each do |mapper_sym|
-      mapper = mapper_for(mapper_sym)
+    version = get_version!(version_name)
+    version.mappers_order.each do |mapper_sym|
+      mapper = version.mapper_for(mapper_sym)
       mapper_key_name = mapper.name.to_s.downcase
       
       mapper_default_value = mapper.default_value
@@ -79,9 +88,4 @@ class Jsoning::Protocol
 
     data
   end
-
-  private
-  def canonical_name(key_name)
-    key_name.to_s.downcase.to_sym
-  end
 end

data/lib/jsoning/foundations/version.rb

@@ -0,0 +1,38 @@
+# jsoning can output to conform to different versioning
+class Jsoning::Version
+  attr_reader :version_name
+
+  # the protocol class
+  attr_reader :protocol
+
+  attr_reader :mappers
+  attr_reader :mappers_order
+
+  def initialize(protocol)
+    @protocol = protocol
+    # mappers, only storing symbol of mapped values
+    @mappers_order = []
+    @mappers = {}
+  end
+
+  def version_name=(version_name)
+    # version name is always be a string, because if user's version
+    # name happen to be an integer, we don't want to fail on that case
+    @version_name = version_name.to_s
+  end
+
+  def add_mapper(mapper)
+    raise Jsoning::Error, "Mapper must be of class Jsoning::Mapper" unless mapper.is_a?(Jsoning::Mapper)
+    @mappers_order << canonical_mapper_name(mapper.name)
+    @mappers[canonical_mapper_name(mapper.name)] = mapper
+  end
+
+  def mapper_for(name)
+    @mappers[canonical_mapper_name(name)]
+  end
+
+  private
+    def canonical_mapper_name(key_name)
+      key_name.to_s.downcase.to_sym
+    end
+end

data/lib/jsoning/version.rb

@@ -1,3 +1,3 @@
 module Jsoning
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/jsoning.rb

@@ -2,8 +2,9 @@ require "jsoning/version"
 
 require "jsoning/dsl/for_dsl"
 require "jsoning/exceptions/error"
-require "jsoning/foundations/mapper"
 require "jsoning/foundations/protocol"
+require "jsoning/foundations/version"
+require "jsoning/foundations/mapper"
 
 require "json"
 
@@ -42,9 +43,43 @@ module Jsoning
   end
 
   # generate the json document
+  # options:
+  # - hash: specify if the return is a hash
+  # - pretty: only for when hash is set to flash, print JSON pretty
+  # - version: specify the version to be used for the processing
   def generate(object, options = {})
+    Jsoning.initialize_type_extensions
     protocol = protocol_for!(object.class)
-    protocol.generate(object, options)
+
+    # use default version if version is unspecified 
+    options[:version] = :default if options[:version].nil?
+
+    if options[:hash] == true
+      return generate_hash(object, protocol, options)
+    else
+      return generate_json(object, protocol, options)
+    end
+  end
+
+  # generate a JSON object
+  # options:
+  # - pretty: pretty print json data
+  def generate_json(object, protocol, options)
+    pretty = options[:pretty]
+    pretty = options["pretty"] if pretty.nil?
+    pretty = false if pretty.nil?
+
+    data = protocol.retrieve_values_from(object, options)
+
+    if pretty
+      JSON.pretty_generate(data)
+    else
+      JSON.generate(data)
+    end
+  end
+
+  def generate_hash(object, protocol, options)
+    as_hash = protocol.retrieve_values_from(object, options)
   end
 
   @@type_extension_initialized = false
@@ -84,12 +119,13 @@ module Jsoning
     end
   end
 
+  # using [] will generate using default schema
   def [](object) 
-    Jsoning.initialize_type_extensions 
-    protocol = protocol_for!(object.class)
-    protocol.retrieve_values_from(object)
+    generate(object, hash: true, version: :default)
   end
 
+  # add custom type explaining to Jsoning how Jsoning should extract value from
+  # this kind of class
   def add_type(klass, options = {})
     processor = options[:processor]
     raise Jsoning::Error, "Pass in processor that is a proc explaining how to extract the value" unless processor.is_a?(Proc)
@@ -102,15 +138,14 @@ module Jsoning
     private
 
     def Jsoning(object, options = {})
-      Jsoning.initialize_type_extensions 
       Jsoning.generate(object, options)
     end
   end
 
   # parse the JSON String to Hash
-  def parse(json_string, klass)
+  def parse(json_string, klass, version_name = :default)
     Jsoning.initialize_type_extensions 
     protocol = protocol_for!(klass)
-    protocol.construct_hash_from(json_string)
+    protocol.construct_hash_from(json_string, version_name)
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsoning
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Adam Pahlevi
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-10-03 00:00:00.000000000 Z
+date: 2015-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -78,6 +78,7 @@ files:
 - lib/jsoning/exceptions/error.rb
 - lib/jsoning/foundations/mapper.rb
 - lib/jsoning/foundations/protocol.rb
+- lib/jsoning/foundations/version.rb
 - lib/jsoning/version.rb
 homepage: http://github.com/saveav/jsoning
 licenses: