ruby-serial 1.0.0.20130705

data/AUTHORS

@@ -0,0 +1,3 @@
+= Muriel Salvan (muriel@x-aeon.com)
+
+* 1.0.0.20130705

data/ChangeLog

@@ -0,0 +1,5 @@
+= Ruby-Serial Release History
+
+== 1.0.0.20130705 (Beta)
+
+* Initial public release.

data/Credits

@@ -0,0 +1,11 @@
+= Projects used by RubySerial
+
+== MessagePack
+* Furuhashi Sadayuki (http://twitter.com/frsyuki)
+* http://msgpack.org/
+* Ruby binding used to serialize data in a JSON way
+
+== Ruby
+* Yukihiro « matz » Matsumoto (http://www.rubyist.net/~matz/)
+* http://www.ruby-lang.org/
+* Thanks a lot Matz for this truly wonderful language !

data/LICENSE

@@ -0,0 +1,31 @@
+
+The license stated herein is a copy of the BSD License (modified on July 1999).
+The AUTHOR mentionned below refers to the list of people involved in the
+creation and modification of any file included in the delivered package.
+This list is found in the file named AUTHORS.
+The AUTHORS and LICENSE files have to be included in any release of software
+embedding source code of this package, or using it as a derivative software.
+
+Copyright (c) 2012 - 2013 Muriel Salvan (muriel@x-aeon.com)
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+   1. Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+   2. Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+   3. The name of the author may not be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
+EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
+OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
+OF SUCH DAMAGE.

data/README

@@ -0,0 +1,15 @@
+= Ruby Serial
+
+Optimized serialization library for Ruby objects.
+
+== Where is the documentation ?
+
+Check the website at http://ruby-serial.sourceforge.net
+
+== Who wrote it ?
+
+Check the AUTHORS[link:AUTHORS.html] file.
+
+== What is the license ?
+
+You can find out in the LICENSE[link:LICENSE.html] file.

data/README.md

@@ -0,0 +1,16 @@
+RubySerial
+=============
+
+**Optimized serialization library for Ruby objects.**
+
+Library serializing Ruby objects, optimized in many ways:
+* Space efficient: Use MessagePack (binary compact storage) and don't serialize twice the same object
+* Keep shared objects: if an object is shared by others, serialization still keeps the reference and does not duplicate objects in memory
+* Gives the ability to fine tune which attributes of your objects are to be serialized
+* Keeps backward compatibility with previously serialized versions
+
+[See documentation here!](http://ruby-serial.sourceforge.net)
+
+## Contact
+
+Want to contribute? Have any questions? [Contact Muriel!](mailto:muriel@x-aeon.com)

data/Rakefile

@@ -0,0 +1,7 @@
+#!/usr/bin/env rake
+
+task :test do |t|
+  load("#{File.dirname(__FILE__)}/test/run.rb")
+end
+
+task :default => :test

data/ReleaseInfo

@@ -0,0 +1,8 @@
+
+# This file has been generated by RubyPackager during a delivery.
+# More info about RubyPackager: http://rubypackager.sourceforge.net
+{
+  :version => '1.0.0.20130705',
+  :tags => [ 'Beta' ],
+  :dev_status => 'Beta'
+}

data/lib/ruby-serial.rb

@@ -0,0 +1,32 @@
+require 'msgpack'
+require 'ruby-serial/_class'
+require 'ruby-serial/_object'
+require 'ruby-serial/common'
+require 'ruby-serial/serializer'
+require 'ruby-serial/deserializer'
+
+module RubySerial
+
+  # Serialize an object into a String
+  #
+  # Parameters::
+  # * *obj* (_Object_): Object to serialize
+  # * *options* (<em>map<Symbol,Object></em>): Options [default = {}]
+  #   * *:version* (_String_): The version to be used to encode
+  # Result::
+  # * _String_: Serialized object
+  def self.dump(obj, options = {})
+    return Serializer.new(obj, options).dump
+  end
+
+  # Deserialize an object from a String
+  #
+  # Parameters::
+  # * *data* (_String_): Data to deserialize
+  # Result::
+  # * _Object_: Corresponding Ruby object
+  def self.load(data)
+    return Deserializer.new(data).load
+  end
+
+end

data/lib/ruby-serial/_class.rb

@@ -0,0 +1,28 @@
+class Class
+
+  attr_reader :dont_rubyserial_lst
+  attr_reader :rubyserial_only_lst
+
+  # Mark some attributes to not be serialized
+  #
+  # Parameters::
+  # * *lst* (<em>list<Symbol></em>): List of attributes symbols
+  def dont_rubyserial(*lst)
+    lst = [lst] if (!lst.is_a?(Array))
+    @dont_rubyserial_lst = [] if (!defined?(@dont_rubyserial_lst))
+    @dont_rubyserial_lst.concat(lst.map { |var_name| "@#{var_name.to_s}".to_sym })
+    @dont_rubyserial_lst.uniq!
+  end
+
+  # Mark some attributes to be serialized
+  #
+  # Parameters::
+  # * *lst* (<em>list<Symbol></em>): List of attributes symbols
+  def rubyserial_only(*lst)
+    lst = [lst] if (!lst.is_a?(Array))
+    @rubyserial_only_lst = [] if (!defined?(@rubyserial_only_lst))
+    @rubyserial_only_lst.concat(lst.map { |var_name| "@#{var_name.to_s}".to_sym })
+    @rubyserial_only_lst.uniq!
+  end
+
+end

data/lib/ruby-serial/_object.rb

@@ -0,0 +1,40 @@
+class Object
+
+  # Get the list of instance variables that are meant to be serialized
+  #
+  # Result::
+  # * <em>map<String,Object></em>: Set of instance variables, per name
+  def get_instance_vars_to_rubyserial
+    # Compute the list of attributes to serialize
+    instance_var_names = []
+    klass = self.class
+    if (klass.rubyserial_only_lst != nil)
+      if (klass.dont_rubyserial_lst != nil)
+        instance_var_names = klass.rubyserial_only_lst - klass.dont_rubyserial_lst
+      else
+        instance_var_names = klass.rubyserial_only_lst
+      end
+    elsif (klass.dont_rubyserial_lst != nil)
+      instance_var_names = self.instance_variables - klass.dont_rubyserial_lst
+    else
+      instance_var_names = self.instance_variables
+    end
+    # Compute the resulting map
+    instance_vars = {}
+    instance_var_names.each do |sym_var|
+      instance_vars[sym_var.to_s] = self.instance_variable_get(sym_var)
+    end
+    return instance_vars
+  end
+
+  # Set the list of instance variables that were serialized
+  #
+  # Parameters::
+  # * *instance_vars* (<em>map<String,Object></em>): Set of instance variables, per name
+  def set_instance_vars_from_rubyserial(instance_vars)
+    instance_vars.each do |var_name, value|
+      self.instance_variable_set(var_name.to_sym, value)
+    end
+  end
+
+end

data/lib/ruby-serial/common.rb

@@ -0,0 +1,10 @@
+module RubySerial
+
+  # Find shortest strings that are unlikely to get in functional Hashes' keys
+  # !!! Use UTF-8 encoding as otherwise MessagePack won't be able to read data correctly
+  OBJECT_ID_REFERENCE = "\x00\xA0".force_encoding(Encoding::UTF_8)
+  OBJECT_CONTENT_REFERENCE = "\x00\xF1".force_encoding(Encoding::UTF_8)
+  OBJECT_CLASSNAME_REFERENCE = "\x00\xBB".force_encoding(Encoding::UTF_8)
+  SYMBOL_ID = "\x00\xEE".force_encoding(Encoding::UTF_8)
+
+end

data/lib/ruby-serial/deserializer.rb

@@ -0,0 +1,38 @@
+module RubySerial
+
+  # Deserialize data previously serialized using Serializer
+  class Deserializer
+
+    # Constructor
+    #
+    # Parameters::
+    # * *data* (_String_): Serialized data (should be BINARY encoding only)
+    def initialize(data)
+      @data = data
+    end
+
+    # Load the serialized object
+    #
+    # Result::
+    # * _Object_: The deserialized object
+    def load
+      # Find the version
+      idx_data_separator = @data.index("\x00")
+      raise 'Unknown format of data. It appears this data has not been serialized using RubySerial.' if (idx_data_separator == nil)
+      version = @data[0..idx_data_separator-1]
+      data = @data[idx_data_separator+1..-1]
+
+      deserializer = nil
+      begin
+        require "ruby-serial/versions/#{version}/deserializer"
+        deserializer = eval("RubySerial::Deserializer::Versions::Version_#{version}")::Deserializer.new
+      rescue
+        raise "Unknown deserializer version #{version}. Please use a most recent version of RubySerial to decode your data. #{$!}"
+      end
+
+      return deserializer.unpack_data(data)
+    end
+
+  end
+
+end

data/lib/ruby-serial/serializer.rb

@@ -0,0 +1,42 @@
+module RubySerial
+
+  class Serializer
+
+    # Default encoding version (should be the last one)
+    DEFAULT_VERSION = '1'
+
+    # Constructor
+    #
+    # Parameters::
+    # * *obj* (_Object_): Ruby object to serialize
+    # * *options* (<em>map<Symbol,Object></em>): Options [default = {}]
+    #   * *:version* (_String_): The version to be used to encode
+    def initialize(obj, options = {})
+      @version = (options[:version] || DEFAULT_VERSION)
+      @obj = obj
+      # Map of objects ID, with their corresponding number of shared objects among their descendants (those having 0 share nothing)
+      # map< ObjectID, NbrSharedObjects >
+      @objs = {}
+      # Map of shared objects' associated to a boolean indicating whether they have already been serialized or not
+      @shared_objs = {}
+    end
+
+    # Serialize the object
+    #
+    # Result::
+    # * _String_: The object serialized
+    def dump
+      serializer = nil
+      begin
+        require "ruby-serial/versions/#{@version}/serializer"
+        serializer = eval("RubySerial::Serializer::Versions::Version_#{@version}")::Serializer.new
+      rescue
+        raise "Unknown serializer version #{@version}: #{$!}"
+      end
+
+      return "#{@version}\x00#{serializer.pack_data(@obj)}".force_encoding(Encoding::BINARY)
+    end
+
+  end
+
+end

data/lib/ruby-serial/versions/1/deserializer.rb

@@ -0,0 +1,99 @@
+module RubySerial
+
+  class Deserializer
+
+    module Versions
+
+      module Version_1
+
+        class Deserializer
+
+          # Unpack data
+          #
+          # Parameters::
+          # * *data* (_String_): Data to deserialize
+          # Result::
+          # * _Object_: The unpacked data
+          def unpack_data(data)
+            decoded_data = MessagePack::unpack(data)
+            if (decoded_data['shared_objs'].empty?)
+              return get_original_rec(decoded_data['obj'])
+            else
+              # We need to replace some data before
+              @serialized_shared_objs = decoded_data['shared_objs']
+              @decoded_shared_objs = {}
+              return get_original_rec(decoded_data['obj'])
+            end
+          end
+
+          private
+
+          # Convert back a deserialized object using MessagePack to the original object
+          #
+          # Parameters::
+          # * *obj* (_Object_): The decoded object
+          # * *container_to_fill* (_Object_): The container to fill with the decoded data. If nil, a new object will be created. [default = nil]
+          # Result::
+          # * _Object_: The original object
+          def get_original_rec(decoded_obj, container_to_fill = nil)
+            if (decoded_obj.is_a?(Array))
+              if (container_to_fill == nil)
+                return decoded_obj.map { |serialized_item| get_original_rec(serialized_item) }
+              else
+                decoded_obj.each do |item|
+                  container_to_fill << get_original_rec(item)
+                end
+                return container_to_fill
+              end
+            elsif (decoded_obj.is_a?(Hash))
+              # Check for special hashes
+              if (decoded_obj[OBJECT_ID_REFERENCE] == nil)
+                if (decoded_obj[OBJECT_CLASSNAME_REFERENCE] == SYMBOL_ID)
+                  return decoded_obj[OBJECT_CONTENT_REFERENCE].to_sym
+                elsif (decoded_obj[OBJECT_CLASSNAME_REFERENCE] == nil)
+                  # Normal hash
+                  hash_obj = ((container_to_fill == nil) ? {} : container_to_fill)
+                  decoded_obj.each do |serialized_key, serialized_value|
+                    hash_obj[get_original_rec(serialized_key)] = get_original_rec(serialized_value)
+                  end
+                  return hash_obj
+                else
+                  # We deserialize a home-made object
+                  # Instantiate the needed class
+                  new_obj = ((container_to_fill == nil) ? eval(decoded_obj[OBJECT_CLASSNAME_REFERENCE]).new : container_to_fill)
+                  instance_vars = {}
+                  decoded_obj[OBJECT_CONTENT_REFERENCE].each do |var_name, serialized_value|
+                    instance_vars[var_name] = get_original_rec(serialized_value)
+                  end
+                  new_obj.set_instance_vars_from_rubyserial(instance_vars)
+                  return new_obj
+                end
+              else
+                # We have a reference to a shared object
+                obj_id = decoded_obj[OBJECT_ID_REFERENCE]
+                if (@decoded_shared_objs[obj_id] == nil)
+                  # Instantiate it already for cyclic decoding (avoids infinite loops)
+                  @decoded_shared_objs[obj_id] = eval(@serialized_shared_objs[obj_id][0]).new
+                  get_original_rec(@serialized_shared_objs[obj_id][1], @decoded_shared_objs[obj_id])
+                end
+                return @decoded_shared_objs[obj_id]
+              end
+            elsif (container_to_fill == nil)
+              # Should be only String
+              return decoded_obj
+            else
+              # Should be only String
+              container_to_fill.replace(decoded_obj)
+              return container_to_fill
+            end
+          end
+
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/ruby-serial/versions/1/serializer.rb

@@ -0,0 +1,140 @@
+module RubySerial
+
+  class Serializer
+
+    module Versions
+
+      module Version_1
+
+        class Serializer
+
+          # Get data
+          #
+          # Parameters::
+          # * *obj* (_Object_): Object to pack
+          # Result::
+          # * _String_: The serialized data
+          def pack_data(obj)
+            # First look for shared objects
+            # Set of objects parsed, per object_id
+            @objs = {}
+            # Set of shared object_id, with a boolean indicating whether they have been serialized already or not
+            @shared_objs = {}
+            gather_ids_rec(obj)
+            @shared_objs_to_store = {}
+            @shared_objs.each do |object_id, false_value|
+              @shared_objs_to_store[object_id] = [
+                @objs[object_id].class.name,
+                get_msgpack_compatible_rec(@objs[object_id], false)
+              ]
+            end
+            #puts "Found #{@shared_objs_to_store.size} shared objects to be stored"
+            return {
+              'obj' => get_msgpack_compatible_rec(obj),
+              'shared_objs' => @shared_objs_to_store
+            }.to_msgpack.force_encoding(Encoding::BINARY)
+          end
+
+          private
+
+          # Gather all shared objects in @shared_objs, tracking which ones have already been parsed in @objs.
+          # Called recursively on all objects contained in obj.
+          #
+          # Parameters::
+          # * *obj* (_Object_): The object to inspect
+          def gather_ids_rec(obj)
+            if ((!obj.is_a?(Fixnum)) and
+                (!obj.is_a?(Bignum)) and
+                (!obj.is_a?(Float)) and
+                (!obj.is_a?(Symbol)) and
+                (obj != nil) and
+                (obj != true) and
+                (obj != false))
+              # Check if obj id is shared
+              if (@objs[obj.object_id] == nil)
+                # First time we encounter this object
+                @objs[obj.object_id] = obj
+                # See other references
+                if (obj.is_a?(Array))
+                  obj.each_with_index do |item, idx|
+                    gather_ids_rec(item)
+                  end
+                elsif (obj.is_a?(Hash))
+                  obj.each do |key, value|
+                    gather_ids_rec(value)
+                    gather_ids_rec(key)
+                  end
+                else
+                  # Handle other objects
+                  obj.get_instance_vars_to_rubyserial.each do |var_name, var|
+                    gather_ids_rec(var)
+                  end
+                end
+              else
+                # This object is shared.
+                @shared_objs[obj.object_id] = false
+              end
+            end
+          end
+
+          # Convert the object (and all its descendants) to be serializable using to_msgpack without loosing information.
+          #
+          # Parameters::
+          # * *obj* (_Object_): Object to convert
+          # * *check_shared* (_Boolean_): Do we check whether this object is shared? [default = true]
+          # Result::
+          # * _Object_: The object ready to be serialized
+          def get_msgpack_compatible_rec(obj, check_shared = true)
+            if ((obj.is_a?(Fixnum)) or
+                (obj.is_a?(Bignum)) or
+                (obj.is_a?(Float)) or
+                (obj == nil) or
+                (obj == true) or
+                (obj == false))
+              return obj
+            elsif (obj.is_a?(Symbol))
+              # TODO (MessagePack): Remove this if MessagePack handles Symbols one day
+              return {
+                OBJECT_CLASSNAME_REFERENCE => SYMBOL_ID,
+                OBJECT_CONTENT_REFERENCE => obj.to_s
+              }
+            elsif (check_shared and
+                   (@shared_objs[obj.object_id] != nil))
+              # This object is shared: store its object_id only
+              return {
+                OBJECT_ID_REFERENCE => obj.object_id
+              }
+            elsif (obj.is_a?(Array))
+              # First serialize its items
+              return obj.map { |item| get_msgpack_compatible_rec(item) }
+            elsif (obj.is_a?(Hash))
+              # First serialize its items
+              hash_to_store = {}
+              obj.each do |key, value|
+                hash_to_store[get_msgpack_compatible_rec(key)] = get_msgpack_compatible_rec(value)
+              end
+              return hash_to_store
+            elsif (obj.is_a?(String))
+              return obj
+            else
+              # Handle other objects
+              serialized_instance_vars = {}
+              obj.get_instance_vars_to_rubyserial.each do |var_name, value|
+                serialized_instance_vars[var_name] = get_msgpack_compatible_rec(value)
+              end
+              return {
+                OBJECT_CLASSNAME_REFERENCE => obj.class.name,
+                OBJECT_CONTENT_REFERENCE => serialized_instance_vars
+              }
+            end
+          end
+
+        end
+
+      end
+
+    end
+
+  end
+
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: ruby-serial
+version: !ruby/object:Gem::Version
+  version: 1.0.0.20130705
+  prerelease: 
+platform: ruby
+authors:
+- Muriel Salvan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-07-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: msgpack
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ! 'Library serializing Ruby objects, optimized in many ways:
+
+  * Space efficient: Use MessagePack (binary compact storage) and don''t serialize
+  twice the same object
+
+  * Keep shared objects: if an object is shared by others, serialization still keeps
+  the reference and does not duplicate objects in memory
+
+  * Gives the ability to fine tune which attributes of your objects are to be serialized
+
+  * Keeps backward compatibility with previously serialized versionsRuby library giving
+  block-buffered and cached read over IO objects with a String-like interface. Ideal
+  to parse big files as Strings, limiting memory consumption.'
+email: muriel@x-aeon.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- AUTHORS
+- ChangeLog
+- Credits
+- lib/ruby-serial/common.rb
+- lib/ruby-serial/deserializer.rb
+- lib/ruby-serial/serializer.rb
+- lib/ruby-serial/versions/1/deserializer.rb
+- lib/ruby-serial/versions/1/serializer.rb
+- lib/ruby-serial/_class.rb
+- lib/ruby-serial/_object.rb
+- lib/ruby-serial.rb
+- LICENSE
+- Rakefile
+- README
+- README.md
+- ReleaseInfo
+homepage: http://ruby-serial.sourceforge.net
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: ruby-serial
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Optimized serialization library for Ruby objects.
+test_files: []