rughetto-ar_object_pack 0.0.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Rue The Ghetto
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,40 @@
+ar_object_pack
+==============
+
+A Merb/Rails plugin for ActiveRecord that pack objects into text strings easy storage in the database. 
+
+Advances in ORMs like DataMapper have introduced data types that allow rich data objects to be packed into the database. From early on ActiveRecord came with the #serialize method, that adds this functionality via YAML. The implementation of YAML in Ruby is very slow, making serialization this way approximately 30 to 100 times slower that serializing via data marshaling, depending on the complexity of the object. 
+
+This plugin allows objects to be packaged into the database using Marshal, JSON, or YAML. In addition, marshaled objects can be encoded using base 64 to prevent problems with character sets in the query string.
+
+
+INSTALLATION
+============
+ar_object_pack is a gem hosted at github. To add github as a source for gems, run this on command:
+  gem sources -a http://gems.github.com
+The gem can then be installed on the command line via
+  sudo gem install rughetto-ar_object_pack
+
+If using Merb, adding the gem as a dependency will also load the required methods into ActiveRecord Base. For other frameworks, add to the application initialization the following lines of code:
+
+  require File.dirname(__FILE__) + PATH_TO_GEM_LIB_DIR +'/ar_object_pack/object_packer'
+  ActiveRecord::Base.send(:extend, ArObjectPack::ObjectPackager::ActiveRecordMethods)
+
+PATH_TO_GEM_LIB_DIR above should be replaced by the relative path from the initialization file to the gem library. Hopefully soon a init.rb file will allow easy Rails plugin ability too.
+
+
+USAGE
+===== 
+ar_object_pack adds the #package method to ActiveRecord base. That means that in the model class definition, any text holding field can be specified as a packaged object. 
+
+  class PackagedThing < ActiveRecord::Base
+    package :obj              # defaults to :marshal
+    package :obj_marshal,     :marshal
+    package :obj_yaml,        :yaml
+    package :obj_json,        :json
+    package :obj_marshal_64,  :marshal_64
+  end
+
+#package takes two arguments
+  1) database_attribute: This can be of type either string or a symbol. If the text does not correspond to a model database attribute, an argument exception will be raised.
+  2) package_method: This is an optional argument with the default value being :marshal. The value can also be passed as either a string or a symbol. Currently there are the values as seen in above example.  

data/Rakefile

@@ -0,0 +1,60 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'spec/rake/spectask'
+
+require 'merb-core'
+require 'merb-core/tasks/merb'
+
+GEM_NAME =    "ar_object_pack"
+GEM_VERSION = "0.0.1"
+AUTHOR =      "Rue The Ghetto"
+EMAIL =       "ru_ghetto@rubyghetto.com"
+HOMEPAGE =    "http://github.com/ru_ghetto/ar_object_pack"
+SUMMARY =     "ActiveRecord plugin originally designed for Merb use that allows the packaging of objects into formats: marshal, json and yaml."
+
+spec = Gem::Specification.new do |s|
+  s.rubyforge_project = 'merb'
+  s.name = GEM_NAME
+  s.version = GEM_VERSION
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README", "LICENSE", 'TODO']
+  s.summary = SUMMARY
+  s.description = s.summary
+  s.author = AUTHOR
+  s.email = EMAIL
+  s.homepage = HOMEPAGE
+  
+  s.add_dependency('active_record')
+  s.add_dependency('json')
+  
+  s.require_path = 'lib'
+  s.files = %w(LICENSE README Rakefile TODO) + Dir.glob("{lib,spec}/**/*")
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+desc "install the plugin as a gem"
+task :install do
+  Merb::RakeHelper.install(GEM_NAME, :version => GEM_VERSION)
+end
+
+desc "Uninstall the gem"
+task :uninstall do
+  Merb::RakeHelper.uninstall(GEM_NAME, :version => GEM_VERSION)
+end
+
+desc "Create a gemspec file"
+task :gemspec do
+  File.open("#{GEM_NAME}.gemspec", "w") do |file|
+    file.puts spec.to_ruby
+  end
+end
+
+Spec::Rake::SpecTask.new do |t|
+   t.warning = true
+   t.spec_opts = ["--format", "specdoc", "--colour"]
+   t.spec_files = Dir['spec/**/*_spec.rb'].sort   
+end

data/TODO

@@ -0,0 +1,4 @@
+TODO:
+
+Add Rails plugin initialization file(s).
+Think about validations, etc for packaging enumerable values and other useful objects from Datamapper

data/lib/ar_object_pack/object_packer.rb

@@ -0,0 +1,95 @@
+require 'json'
+require 'yaml'
+
+module ArObjectPack
+  module ObjectPackager
+    # these methods are added directly to the active record base
+    # for use like
+    #   MyNewClass < ActiveRecord::Base
+    #     package field_name, :marshall 
+    #   end
+    # arguments: meth 
+    module ActiveRecordMethods
+      def package( meth, pack_type=:marshal )
+        raise ArgumentError, "#{meth} is not a database attribute " unless self.new.attributes.keys.include?( meth.to_s )
+        include ArObjectPack::ObjectPackager::InstanceMethods unless self.respond_to?(:do_pack)
+        
+        pack_type = :marshal unless pack_formats.include?( pack_type )
+        self.class_eval %{
+          # create new reader 
+          def #{meth}
+            unpack(self[:#{meth}], '#{pack_type}')
+          end
+          
+          # create new writer
+          def #{meth}=(val)
+            begin
+              self[:#{meth}] = pack(val, '#{pack_type}')
+            rescue => e
+              raise ArgumentError, "Unable to package this object using #{pack_type}: message - " + e.message
+            end    
+          end  
+        }
+      end
+      
+      private
+        def pack_formats
+          formats = [:marshal, :json, :yaml, :marshal_64]
+          formats | formats.collect(&:to_s)
+        end
+    end
+    
+    module InstanceMethods
+      private
+        def unpack(p_object, pack_type)
+          if p_object.class == String
+            loaded = do_pack( pack_type ) do |klass, pack_encode|
+              # decode if required
+              decoded = pack_encode ? Base64.decode64( p_object ) : p_object 
+              # use the class to load the data
+              decoded = klass.load( decoded )
+              return decoded 
+            end  
+          else
+            loaded = p_object
+          end    
+          loaded
+        end
+      
+        def pack(p_object, pack_type)
+          do_pack( pack_type ) do |klass, pack_encode|
+            # pack using class
+            if klass == JSON
+              JSON.dump( p_object)
+            end  
+            dumped = klass.dump( p_object )
+            # encode if necessary
+            dumped = Base64.encode64( dumped ) if pack_encode
+            return dumped
+          end  
+        end  
+      
+        def do_pack( pack_type )
+          # determine base pack type and encoding
+          pack_type = pack_type.to_s
+          pack_encode = false
+          if pack_type.include?( "64" )
+            pack_encode = true
+            pack_type = pack_type[0 .. pack_type.length-4]
+          end  
+          
+          case pack_type
+          when "json"
+            klass = JSON
+          when "yaml"
+            klass = YAML
+          else
+            klass = Marshal
+          end  
+          
+          yield( klass, pack_encode )
+        end  
+      public  
+    end      
+  end  
+end

data/lib/ar_object_pack.rb

@@ -0,0 +1,18 @@
+# make sure we're running inside Merb
+if defined?(Merb::Plugins)
+
+  # Merb gives you a Merb::Plugins.config hash...feel free to put your stuff in your piece of it
+  Merb::Plugins.config[:ar_object_pack] = {}
+  
+  Merb::BootLoader.before_app_loads do
+    # load ObjectPacker into AR Base
+    require File.dirname(__FILE__) + '/ar_object_pack/object_packer'
+    ActiveRecord::Base.send(:extend, ArObjectPack::ObjectPackager::ActiveRecordMethods)
+  end
+  
+  Merb::BootLoader.after_app_loads do
+    # code that can be required after the application loads
+  end
+  
+  # Merb::Plugins.add_rakefiles "ar_object_pack/merbtasks"
+end

data/spec/ar_object_pack_spec.rb

@@ -0,0 +1,188 @@
+# helper
+require File.dirname(__FILE__) + '/spec_helper'
+
+# gems for testing
+require 'rubygems'
+require 'active_record'
+require 'sqlite3'
+
+# files for testing
+require File.dirname(__FILE__) + '/../lib/ar_object_pack/object_packer'
+
+# establish database and test classes
+require File.dirname(__FILE__) + "/database_spec_setup"
+include DatabaseSpecSetup
+
+describe "ar_object_pack" do
+  describe "testing setup: " do
+    it "have all the needed gems and files to run" do
+      # before block should not throw error and the following should pass!
+      true.should == true
+    end  
+    
+    it "should save and retrieve test records normally" do
+      testing = Testing.new(:str => "my new string")
+      testing.should be_new_record
+      testing.save
+      testing.should_not be_new_record
+      testing.str.should == "my new string"
+    end  
+  end  
+  
+  describe "Methods are added to ActiveRecord::Base, " do
+    it '#package is a method available in ActiveRecord::Base' do
+      ActiveRecord::Base.methods.include?( "package" ).should == true
+    end  
+  end  
+  
+  describe 'packaging objects, ' do
+    before(:each) do  
+      @object = ['1','2','3']
+      @instance = Package.new
+    end  
+    
+    it "using the AR package call should not raise errors" do
+      lambda {
+        instance = Package.new
+      }.should_not raise_error
+    end  
+    
+    describe "default pack method" do
+      it "should have private methods for pack, unpack and do_pack" do
+        @instance.private_methods.should include('pack')
+        @instance.private_methods.should include('unpack')
+        @instance.private_methods.should include('do_pack')
+      end 
+    
+      it "should pack a field attribute using Marshal if no pack method is defined" do
+        Marshal.should_receive(:dump).at_least(:once)
+        @instance.obj = @object
+      end  
+      
+      it "should unpack a field attribute using Marshal if no pack method is defined" do
+        Marshal.should_receive(:load).at_least(:once)
+        @instance.obj = @object
+        @instance.obj
+      end 
+    end
+
+    describe "explicit Marshal packing" do
+      it "should pack a field attribute using Marshal when that option is specified" do
+        Marshal.should_receive(:dump).at_least(:once)
+        @instance.obj_marshal = @object
+      end  
+      
+      it "should unpack a field attribute using Marshal when that option is specified" do
+        Marshal.should_receive(:load).at_least(:once)
+        @instance.obj_marshal = @object
+        @instance.obj_marshal
+      end
+  
+      it "an object should be the same after packing, saving and unpacking with Marshal method" do
+        @instance.obj_marshal = @object
+        @instance.save
+        @instance.reload
+        @instance.obj_marshal.should == @object
+      end
+    end
+        
+    describe "YAML packing" do
+      it "should pack a field attribute using YAML when that option is specified" do
+        YAML.should_receive(:dump).at_least(:once)
+        @instance.obj_yaml = @object
+      end  
+
+      it "should unpack a field attribute using YAML when that option is specified" do
+        YAML.should_receive(:load).at_least(:once)
+        @instance.obj_yaml = @object
+        @instance.obj_yaml
+      end
+  
+      it "an object should be the same after packing and unpacking with YAML method" do
+        @instance.obj_yaml = @object
+        @instance.save
+        @instance.reload
+        @instance.obj_yaml.should == @object
+      end
+      
+      it "object should not be packed in the same way as marshal" do
+        @instance.obj_yaml = @object
+        @instance.obj = @object
+        @instance[:obj_yaml].should_not == @instance[:obj]
+      end  
+    end  
+    
+    describe "JSON packing" do
+      it "should pack a field attribute using JSON when that option is specified" do
+        JSON.should_receive(:dump).at_least(:once)
+        @instance.obj_json = @object
+      end  
+
+      it "should unpack a field attribute using JSON when that option is specified" do
+        JSON.should_receive(:load).at_least(:once)
+        @instance.obj_json = @object
+        @instance.obj_json
+      end
+  
+      it "an object should be the same after packing and unpacking with JSON method" do
+        @instance.obj_json = @object
+        @instance.save
+        @instance.reload
+        @instance.obj_json == @object
+      end
+      
+      it "object should not be packed in the same way as marshal" do
+        @instance.obj_json = @object
+        @instance.obj = @object
+        @instance[:obj_json].should_not == @instance[:obj]
+      end  
+    end
+    
+    describe "Encoding with packing" do
+      it "should encode a field attribute when that option is specified in the pack_type" do
+        Base64.should_receive(:encode64).at_least(:once)
+        @instance.obj_marshal_64 = @object
+      end  
+      
+      it "should decode a field attribute when that option is specified in the pack_type" do
+        # This seems to be failing even though it is actually working. 
+        # The error is bubbling up from the C code. If the should_receive directive is taken out 
+        # of the mix no error is raised. So it may be some weirdness with the interaction between
+        # Marshal and rpsec ??
+        Base64.should_receive("decode64").at_least(:once)
+        @instance.obj_marshal_64 = @object
+        @instance.obj_marshal_64
+      end
+  
+      it "an object should be the same after packing, saving and unpacking when using encoded data" do
+        @instance.obj_marshal_64 = @object
+        @instance.save
+        @instance.reload
+        @instance.obj_marshal_64.should == @object
+      end
+      
+      it "object should not be packed in the same way as unencoded marshal" do
+        @instance.obj_marshal_64 = @object
+        @instance.obj = @object
+        @instance[:obj_marshal_64].should_not == @instance[:obj]
+        @instance[:obj_marshal_64].should_not == @object
+      end
+    end  
+    
+    describe "an exception should be thrown if" do
+      it "packaging method is unable to pack the object" do
+        lambda{
+          @instance.obj_json = {:something => :else}
+        }.should raise_error
+      end  
+      
+      it "package is called on the class for a method name that does not belong to a field attribute" do
+        lambda {
+          class Package
+            package :not_a_field
+          end
+        }.should raise_error
+      end  
+    end  
+  end  
+end

data/spec/database_spec_setup.rb

@@ -0,0 +1,42 @@
+module DatabaseSpecSetup
+  # remove the old database 
+  File.delete("object_pack_tester.db")  if File.file?("object_pack_tester.db")
+
+  # send methods to base
+  ActiveRecord::Base.send(:extend, ArObjectPack::ObjectPackager::ActiveRecordMethods)
+
+  # establish a connection to the sqlite database
+  ActiveRecord::Base.establish_connection(
+    :adapter =>   'sqlite3',
+    :database =>  'object_pack_tester.db'
+  )
+
+  # define a schema
+  ActiveRecord::Schema.define do
+    # table for testing different packages
+    create_table :packages, :force => true do |t|
+      t.column :obj,            :text
+      t.column :obj_marshal,    :text
+      t.column :obj_yaml,       :text
+      t.column :obj_json,       :text
+      t.column :obj_marshal_64, :text
+    end
+  
+    # table for testing basic database writes and reads to ensure correct setup
+    create_table :testings, :force => true do |t|
+      t.column :str, :string
+    end  
+  end
+
+  # Related classes
+  class Package < ActiveRecord::Base
+    package :obj
+    package :obj_marshal,     :marshal
+    package :obj_yaml,        :yaml
+    package :obj_json,        :json
+    package :obj_marshal_64,  :marshal_64
+  end  
+  
+  class Testing < ActiveRecord::Base; end
+  
+end  

data/spec/irb_tester.rb

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+
+# This script is modified from one written by Erik Kastner, 
+# and a blog describing it's needs and usage can be found at 
+# http://metaatem.net/2007/04/20/fun-with-active_record-and-sqlite3
+# 
+# It can be used for hands on quick and dirty testing to see how the library 
+# is working in an established class in IRB. It will open an IRB console with
+# the database as specified below, plus the classes defined
+# 
+# This file must be executable to work: [sudo] chmod 775 irb_tester.rb
+# 
+
+require 'rubygems'
+require 'active_record'
+require 'sqlite3'
+require 'irb'
+require 'ruby-debug'
+
+File.delete("irb_test.db")  if File.file?("irb_test.db")
+
+require File.dirname(__FILE__) + '/../lib/ar_object_pack/object_packer'
+ActiveRecord::Base.send(:extend, ArObjectPack::ObjectPackager::ActiveRecordMethods)
+
+require File.dirname(__FILE__) + "/database_spec_setup"
+include DatabaseSpecSetup
+
+IRB.start if __FILE__ == $0

data/spec/spec.opts

@@ -0,0 +1,2 @@
+--colour
+--backtrace

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+$:.push File.join(File.dirname(__FILE__), '..', 'lib')

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification 
+name: rughetto-ar_object_pack
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Rue The Ghetto
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-01-05 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: active_record
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: "ActiveRecord plugin originally designed for Merb use that allows the packaging of objects into formats: marshal, json and yaml."
+email: ru_ghetto@rubyghetto.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- LICENSE
+- TODO
+files: 
+- LICENSE
+- README
+- Rakefile
+- TODO
+- lib/ar_object_pack
+- lib/ar_object_pack/object_packer.rb
+- lib/ar_object_pack.rb
+- spec/ar_object_pack_spec.rb
+- spec/database_spec_setup.rb
+- spec/dbs
+- spec/irb_tester.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/ru_ghetto/ar_object_pack
+post_install_message: 
+rdoc_options: []
+
+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: merb
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: "ActiveRecord plugin originally designed for Merb use that allows the packaging of objects into formats: marshal, json and yaml."
+test_files: []
+