birkirb-acts_as_serializable 0.1.0

data/README.rdoc

@@ -0,0 +1,77 @@
+= acts_as_serializable
+
+by Birkir A. Barkarson <birkirb@stoicviking.net>
+
+== Description
+
+A gem/rails plugin for handling versioning of serialization methods (to_xml, to_json).
+Uses the builder pattern for a one stop multi-format serialization method, which can be
+versioned in-class, in a module or in seperately managed class files.
+
+== Installation from source
+
+  git clone git://github.com/birkirb/acts_as_serializable.git
+  cd acts_as_serializable
+  rake install
+
+=== Gem Installation
+
+  gem install birkirb-acts_as_serializable --source http://gems.github.com
+
+== Examples
+
+First:
+
+  require 'rubygems'
+  require 'acts_as_serializable'
+
+
+Define your own serialization method:
+
+  class SimpleClass
+    include Serializable
+    acts_as_serializable
+
+    def serialize(builder, options)
+      builder.root do
+        builder.text 'hello world'
+      end
+    end
+  end
+
+  SimpleClass.new.to_xml => "<root><text>hello world</text></root>"
+  SimpleClass.new.to_hash => {:text=>"hello world"}
+  SimpleClass.new.to_json => "{\"text\": \"hello world\"}"
+
+Use versioned serialization methods:
+
+  class SimpleClass
+    include Serializable
+
+    def serialize_to_version_1_0(builder, options)
+      builder.root do
+        builder.text 'hello world'
+      end
+    end
+
+    def serialize_to_version_2_0(builder, options)
+      builder.texts do
+        builder.text "It's a brave new world"
+      end
+    end
+
+    acts_as_serializable
+  end
+
+  SimpleClass.new.to_xml => "<texts><text>It's a brave new world</text></texts>" 
+  SimpleClass.new.to_hash(:version => '1.0') => {:text=>"hello world"}
+
+Use classes containing versioned serialization methods:
+
+  WIP
+
+== Copyright
+
+Author::    Birkir A. Barkarson <birkirb@stoicviking.net>
+Copyright:: Copyright (c) 2009
+License::   MIT License

data/Rakefile

@@ -0,0 +1,115 @@
+require 'rake'
+
+begin
+  require 'spec/rake/spectask'
+
+  Spec::Rake::SpecTask.new('spec') do |t|
+    t.spec_opts = ["-f specdoc", "-c"]
+    t.spec_files = FileList['spec/*_spec.rb']
+  end
+
+rescue LoadError
+  desc 'Spec rake task not available'
+  task :spec do
+    abort 'Spec rake task is not available. Be sure to install rspec as a gem or plugin'
+  end
+end
+
+begin
+  require 'cucumber'
+  require 'cucumber/rake/task'
+
+
+  desc "Run Cucumber feature tests"
+  Cucumber::Rake::Task.new(:features) do |t|
+    t.cucumber_opts = "--format pretty" 
+  end
+
+rescue LoadError
+  desc 'Cucumber rake task not available'
+  task :features do
+    abort 'Cucumber rake task is not available. Be sure to install cucumber as a gem or plugin'
+  end
+end
+
+begin
+  require 'spec/rake/spectask'
+  require 'cucumber'
+  require 'cucumber/rake/task'
+  require 'spec/rake/verify_rcov'
+
+  task :test do
+    Rake::Task[:spec].invoke
+    Rake::Task[:features].invoke
+  end
+
+  desc "Run tests with RCov"
+  namespace :rcov do
+    rm "coverage.data" if File.exist?("coverage.data")
+
+    desc "Run Features with RCov"
+    Cucumber::Rake::Task.new(:features) do |t|
+      t.rcov = true
+      t.rcov_opts = %w{ --exclude osx\/objc,gems\/,spec\/,features\/ --aggregate coverage.data}
+      t.rcov_opts << %[-o "coverage"]
+    end
+
+    Spec::Rake::SpecTask.new(:spec) do |t|
+      t.spec_opts = ["-f specdoc", "-c"]
+      t.spec_files = FileList['spec/*_spec.rb']
+      t.rcov = true
+      t.rcov_opts = %w{--exclude "spec/*,gems/*,features/*" --aggregate "coverage.data"}
+    end
+
+    desc "Run both specs and features to generate aggregated coverage"
+    task :all do |t|
+      Rake::Task["rcov:spec"].invoke
+      Rake::Task["rcov:features"].invoke
+    end
+
+    RCov::VerifyTask.new(:verify => 'rcov:all') do |t|
+      t.threshold = 100.0
+      t.index_html = 'coverage/index.html'
+    end
+  end
+rescue LoadError
+  desc 'Rcov rake task not available'
+  task :rcov do
+    abort 'rcov rake task is not available. Be sure to install rspec, rcov and cucumber as a gem or plugin'
+  end
+end
+
+begin
+  require 'metric_fu'
+
+  MetricFu::Configuration.run do |config|
+    #define which metrics you want to use
+    config.metrics  = [:churn, :flog, :flay, :reek, :roodi]
+    config.flay     = { :dirs_to_flay => ['app', 'lib']  } 
+    config.flog     = { :dirs_to_flog => ['app', 'lib']  }
+    config.reek     = { :dirs_to_reek => ['app', 'lib']  }
+    config.roodi    = { :dirs_to_roodi => ['app', 'lib'] }
+    config.saikuro  = { :output_directory => 'scratch_directory/saikuro', 
+      :input_directory => ['app', 'lib'],
+      :cyclo => "",
+      :filter_cyclo => "0",
+      :warn_cyclo => "5",
+      :error_cyclo => "7",
+      :formater => "text"} #this needs to be set to "text"
+    config.churn    = { :start_date => "1 year ago", :minimum_churn_count => 10}
+    config.rcov     = { :test_files => ['test/**/*_test.rb', 
+      'spec/**/*_spec.rb'],
+      :rcov_opts => ["--sort coverage", 
+        "--no-html", 
+        "--text-coverage",
+        "--no-color",
+        "--profile",
+        "--rails",
+        "--exclude /gems/,/Library/,spec"]}
+  end
+
+rescue LoadError
+  # Too bad
+end
+
+task :default => [:test]

data/init.rb

@@ -0,0 +1 @@
+require 'lib/acts_as_serializable'

data/lib/acts_as_serializable.rb

@@ -0,0 +1,109 @@
+require 'builder/xmlmarkup'
+require 'jsonbuilder'
+require 'active_support'
+require 'find'
+require 'versions'
+require 'version'
+
+module Serializable
+  SERIALIZE_TO_VERSION_REGEXP = /^serialize_to_version_((:?\d+_?)+)$/
+  SERIALIZED_CLASS_NAME_REGEXP = /\/version_((:?\d+_?)+)\.rb$/
+
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  module ClassMethods
+    def acts_as_serializable
+      include Serializable::InstanceMethods
+      extend Serializable::SingletonMethods
+      @serialization_versions = Versions.new
+      find_local_serialization_methods
+    end
+  end
+
+  module SingletonMethods
+    def find_project_serialization_classes(project_path)
+      klass_name = self.name
+      serialization_directory = File.join(project_path, 'serializations', klass_name.underscore)
+      Find.find(serialization_directory) do |path|
+        if File.file?(path) && versioned_klass = path.match(SERIALIZED_CLASS_NAME_REGEXP)
+          require path
+          klass = Serializable.const_get("#{klass_name}").const_get("Version_#{versioned_klass[1]}")
+          if klass && klass.respond_to?(:serialize)
+            define_local_serialization_method(versioned_klass[1])
+          end
+        end
+      end
+      @default_serialization_version = @serialization_versions.last
+    end
+
+    def serialization_versions
+      @serialization_versions
+    end
+
+    def default_serialization_version
+      @default_serialization_version
+    end
+
+    def default_serialization_version=(new_version)
+      if new_version.is_a?(Version)
+        @default_serialization_version = new_version
+      else
+        @default_serialization_version = Version.new(new_version)
+      end
+    end
+
+    private
+
+    def find_local_serialization_methods
+      self.instance_methods.each do |method_name|
+        if method_name = method_name.match(SERIALIZE_TO_VERSION_REGEXP)
+          @serialization_versions << Version.new(method_name[1])
+        end
+      end
+      @default_serialization_version = @serialization_versions.last
+    end
+
+    def define_local_serialization_method(method_version)
+      class_eval <<-EOV
+        def serialize_to_version_#{method_version}(builder, options)
+          Serializable::#{self.name}::Version_#{method_version}.serialize(self, builder, options)
+        end
+      EOV
+      @serialization_versions << Version.new(method_version)
+    end
+  end
+
+  # This module contains instance methods
+  module InstanceMethods
+    def to_hash(options = {})
+      serialize(Builder::Hash.new, options)
+    end
+
+    def to_json(options = {})
+      serialize(Builder::Json.new, options)
+    end
+
+    def to_xml(options = {})
+      serialize(Builder::XmlMarkup.new, options)
+    end
+
+    def serialize(builder, options = {})
+      if version_number = options[:version]
+        if version = self.class.serialization_versions.find_version(Version.new(version_number))
+          return self.send("serialize_to_version_#{version.to_s_underscored}", builder, options)
+        else
+          raise "Version #{version_number} given but no serialization method found"
+        end
+      else
+        if version = self.class.default_serialization_version
+          return self.send("serialize_to_version_#{version.to_s_underscored}", builder, options)
+        else
+          raise "No serialization method found"
+        end
+      end
+    end
+  end
+
+end

data/lib/version.rb

@@ -0,0 +1,83 @@
+module Serializable
+  class Version
+
+    def initialize(version_string)
+      version_string = version_string.gsub('_','.')
+      @levels = version_string.split('.')
+
+      @levels.each_with_index do |number, index|
+        @levels[index] = number.to_i
+      end
+    end
+
+    def major
+      get_level(0)
+    end
+
+    def minor
+      get_level(1)
+    end
+
+    def build
+      get_level(2)
+    end
+
+    def revision
+      get_level(3)
+    end
+
+    def <(rhs)
+      (self <=> rhs) < 0
+    end
+
+    def >(rhs)
+      (self <=> rhs) > 0
+    end
+
+    def ==(rhs)
+      (self <=> rhs) == 0
+    end
+
+    def <=>(rhs)
+      max_levels = @levels.size - 1
+      max_levels = rhs.levels.size - 1 if rhs.levels.size > max_levels
+
+      (0..max_levels).each do |level|
+        lhs_level = @levels[level] || 0
+        rhs_level = rhs.levels[level] || 0
+
+        if lhs_level == rhs_level
+          next
+        else
+          return lhs_level <=> rhs_level
+        end
+      end
+      0 # Ended on an equality
+    end
+
+    def to_s(seperator = '.')
+      @levels.join(seperator)
+    end
+
+    def to_s_underscored
+      to_s('_')
+    end
+
+    protected
+
+    def levels
+      @levels
+    end
+
+    private
+
+    def get_level(level)
+      if @levels.size > level
+        @levels[level]
+      else
+        0
+      end
+    end
+
+  end
+end

data/lib/versions.rb

@@ -0,0 +1,31 @@
+module Serializable
+  class Versions < Array
+
+    def <<(object)
+      super(object)
+      self.sort!
+    end
+
+    def push(object)
+      super(object)
+      self.sort!
+    end
+
+    def find_version(seeking_version)
+      previous_version = nil
+
+      if seeking_version.is_a?(Version)
+        self.each do |version|
+          if version < seeking_version
+            previous_version = version
+          elsif version > seeking_version
+            return previous_version
+          else
+            return version
+          end
+        end
+      end
+      previous_version
+    end
+  end
+end

data/spec/acts_as_serializable_spec.rb

@@ -0,0 +1,168 @@
+require 'spec/spec_helper'
+
+class SerializableObject
+  include Serializable
+
+  def serialize_to_version_1_0_0(builder, options)
+    "This is version 1.0.0"
+  end
+
+  def serialize_to_version_1_5(builder, options)
+    "This is version 1.5.0"
+  end
+
+  def serialize_to_version_2_1(builder, options)
+    "This is version 2.1"
+  end
+
+  acts_as_serializable
+end
+
+class WithSerialize < SerializableObject
+  include Serializable
+  acts_as_serializable
+
+  def serialize(builder, options)
+    builder
+  end
+end
+
+class NoSerializationObject
+  include Serializable
+  acts_as_serializable
+end
+
+class TestModel
+  include Serializable
+  acts_as_serializable
+  find_project_serialization_classes(File.join(File.dirname(__FILE__)))
+end
+
+describe Serializable, 'if included in a class, then that class' do
+
+  it 'should respond to #to_xml(options)' do
+    klass = SerializableObject.new
+    klass.respond_to?("to_xml").should be_true
+  end
+
+  it 'should respond to #to_json(options)' do
+    klass = SerializableObject.new
+    klass.respond_to?("to_hash").should be_true
+  end
+
+  it 'should respond to #to_hash(options)' do
+    klass = SerializableObject.new
+    klass.respond_to?("to_json").should be_true
+  end
+
+  context 'with the serialized method overriden to return the builder' do
+
+    it '#to_xml should return an Builder::XmlMarkup' do
+      klass = WithSerialize.new
+      klass.to_xml.test.should == "<test/>"
+    end
+
+    it '#to_hash should return an Builder::Hash' do
+      klass = WithSerialize.new
+      klass.to_hash.test('value').should == 'value'
+    end
+
+    it '#to_json should return an Builder::Json' do
+      klass = WithSerialize.new
+      klass.to_json.test('value').should == '"value"'
+    end
+  end
+
+end
+
+describe Serializable, 'when included in a class that has multiple versioned serialization methods' do
+
+  context 'and a to_format method is called with a version option' do
+
+    it 'should execute that exact versioned serialization assuming it exists' do
+      klass = SerializableObject.new
+
+      klass.to_xml(:version => '1.0.0').should == "This is version 1.0.0"
+      klass.to_json(:version => '1.5.0').should == "This is version 1.5.0"
+      klass.to_hash(:version => '2.1.0').should == "This is version 2.1"
+    end
+
+    it 'should execute a lower version if an exact one does not exist' do
+      klass = SerializableObject.new
+
+      klass.to_xml(:version => '1.4.0').should == "This is version 1.0.0"
+      klass.to_json(:version => '3.1.0').should == "This is version 2.1"
+    end
+
+    it 'should raise an error if no corresponding version exists' do
+      klass = SerializableObject.new
+
+      lambda { klass.to_hash(:version => '0.1.0') }.should raise_error(RuntimeError, "Version 0.1.0 given but no serialization method found")
+    end
+  end
+
+  context 'and a to_format method is called with no version option' do
+
+    it 'should default to the most recent version if no global default is set' do
+      klass = SerializableObject.new
+
+      klass.to_xml.should == "This is version 2.1"
+    end
+
+    it 'should throw an error if no serialization method exists' do
+      klass = NoSerializationObject.new
+
+      lambda { klass.to_xml }.should raise_error(RuntimeError, "No serialization method found")
+    end
+
+    it 'should use the default method if it is set' do
+      SerializableObject.default_serialization_version = Serializable::Version.new('1.5')
+      klass = SerializableObject.new
+
+      klass.to_xml.should == "This is version 1.5.0"
+    end
+  end
+end
+
+describe Serializable, 'when included in a class that has multiple serialization classes' do
+
+  context 'and a to_format method is called with a version option' do
+
+    it 'should execute that exact versioned serialization assuming it exists' do
+      klass = TestModel.new
+
+      klass.to_xml(:version => '1.0.0').should == "This is version 1.0.0 for TestModel"
+      klass.to_json(:version => '1.5.0').should == "This is version 1.5.0 for TestModel"
+      klass.to_hash(:version => '2.1.0').should == "This is version 2.1 for TestModel"
+    end
+
+    it 'should execute a lower version if an exact one does not exist' do
+      klass = TestModel.new
+
+      klass.to_xml(:version => '1.4.0').should == "This is version 1.0.0 for TestModel"
+      klass.to_json(:version => '3.1.0').should == "This is version 2.1 for TestModel"
+    end
+
+    it 'should raise an error if no corresponding version exists' do
+      klass = TestModel.new
+
+      lambda { klass.to_hash(:version => '0.1.0') }.should raise_error(RuntimeError, "Version 0.1.0 given but no serialization method found")
+    end
+  end
+
+  context 'and a to_format method is called with no version option' do
+
+    it 'should default to the most recent version if no global default is set' do
+      klass = TestModel.new
+
+      klass.to_xml.should == "This is version 2.1 for TestModel"
+    end
+
+    it 'should use the default method if it is set' do
+      TestModel.default_serialization_version = "1.5"
+      klass = TestModel.new
+
+      klass.to_xml.should == "This is version 1.5.0 for TestModel"
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,6 @@
+require 'rubygems'
+require 'spec'
+
+require 'lib/version'
+require 'lib/versions'
+require 'lib/acts_as_serializable'

data/spec/version_spec.rb

@@ -0,0 +1,75 @@
+require 'spec/spec_helper'
+
+describe Serializable::Version, 'when created with a version numeric string' do
+
+  it 'should report the correct major, minor, build and revision numbers.' do
+    version = Serializable::Version.new('1.2.3.4')
+    version.major.should == 1
+    version.minor.should == 2
+    version.build.should == 3
+    version.revision.should == 4
+  end
+
+  it '#to_s should give the same version string.' do
+    version = Serializable::Version.new('2.1.2')
+    version.to_s.should == '2.1.2'
+  end
+
+  it '#to_s_underscored should give an underscored version string.' do
+    version = Serializable::Version.new('2.1.2')
+    version.to_s_underscored.should == '2_1_2'
+  end
+
+  it 'should give 0 for all numbers not specified.' do
+    version = Serializable::Version.new('3')
+    version.major.should == 3
+    version.minor.should == 0
+    version.build.should == 0
+    version.revision.should == 0
+  end
+
+  it 'should support underscored versions' do
+    version = Serializable::Version.new('3_1_2_4')
+    version.major.should == 3
+    version.minor.should == 1
+    version.build.should == 2
+    version.revision.should == 4
+  end
+end
+
+describe Serializable::Version, 'when comparing two instances' do
+
+  it 'should correctly compare v1.0.0.1 > v.1.0.0.0' do
+    Serializable::Version.new('1.0.0.1').should > Serializable::Version.new('1.0')
+    Serializable::Version.new('1.0.0.1').should_not < Serializable::Version.new('1.0')
+    Serializable::Version.new('1.0.0.1').should_not == Serializable::Version.new('1.0')
+  end
+
+  it 'should correctly compare v1.2.0.3 < v2.2.0.3' do
+    Serializable::Version.new('1.2.0.3').should < Serializable::Version.new('2.2.0.3')
+    Serializable::Version.new('1.2.0.3').should_not > Serializable::Version.new('2.2.0.3')
+    Serializable::Version.new('1.2.0.3').should_not == Serializable::Version.new('2.2.0.3')
+  end
+
+  it 'should correctly compare v2.0.0.0.0.0.0 == v2' do
+    Serializable::Version.new('2.0.0.0.0.0.0.0').should == Serializable::Version.new('2')
+    Serializable::Version.new('2.0.0.0.0.0.0.0').should_not < Serializable::Version.new('2')
+    Serializable::Version.new('2.0.0.0.0.0.0.0').should_not > Serializable::Version.new('2')
+  end
+end
+
+describe Serializable::Version, 'when in an Array' do
+
+  it 'should be sortable' do
+    version_strings_unordered = ['1.20.0', '1.0.2', '1.0.0', '1.4.0', '1.0.1', '2', '1.0.10', '2.0.1', '1.0']
+    version_strings_ordered = ['1.0', '1.0.0', '1.0.1', '1.0.2', '1.0.10', '1.4.0', '1.20.0', '2', '2.0.1']
+    versions = Array.new
+    version_strings_unordered.each do |s|
+      versions << Serializable::Version.new(s)
+    end
+
+    versions.sort.each_with_index do |version, index|
+      version.to_s.should == version_strings_ordered[index]
+    end
+  end
+end

data/spec/versions_spec.rb

@@ -0,0 +1,19 @@
+require 'spec/spec_helper'
+
+describe Serializable::Versions do
+
+  it '#find_version should find a Version equal or less than the Version given ' do
+    version_strings_unordered = ['1.20.0', '1.0.2', '1.0.0', '1.4.0', '1.0.1', '2', '1.0.10', '2.0.1', '1.0']
+    versions = Serializable::Versions.new
+    version_strings_unordered.each do |s|
+      versions << Serializable::Version.new(s)
+    end
+
+    versions.push(Serializable::Version.new('1.3')) # Hmm..
+
+    versions.find_version(Serializable::Version.new('1.30')).should == Serializable::Version.new('1.20.0')
+    versions.find_version(Serializable::Version.new('1.15')).should == Serializable::Version.new('1.4.0')
+    versions.find_version(Serializable::Version.new('1.0.2')).should == Serializable::Version.new('1.0.2')
+    versions.find_version(Serializable::Version.new('3.1.5')).should == Serializable::Version.new('2.0.1')
+  end
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification 
+name: birkirb-acts_as_serializable
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Birkir A. Barkarson
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-06 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: jsonbuilder
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "1.2"
+    version: 
+description: Easy versioning of serialization methods
+email: birkirb@stoicviking.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- Rakefile
+- init.rb
+- lib/acts_as_serializable.rb
+- lib/version.rb
+- lib/versions.rb
+has_rdoc: true
+homepage: http://github.com/birkirb/acts_as_serializable
+post_install_message: 
+rdoc_options: 
+- --title
+- acts_as_serializable documentation
+- --charset
+- utf-8
+- --opname
+- index.html
+- --line-numbers
+- --main
+- README.rdoc
+- --inline-source
+- --exclude
+- ^(examples)/
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Easy versioning of serialization methods
+test_files: 
+- spec/acts_as_serializable_spec.rb
+- spec/version_spec.rb
+- spec/versions_spec.rb
+- spec/spec_helper.rb