aqua 0.1.6 → 0.2.0

data/lib/aqua/object/tank.rb

@@ -1,5 +1,6 @@
 dir = File.dirname(__FILE__)
 require dir + '/pack'
+require dir + '/translator'
 require dir + '/query'
 require dir + '/unpack'
 require dir + '/config'

data/lib/aqua/object/translator.rb

@@ -0,0 +1,313 @@
+module Aqua
+  # Packing of objects needs to save an object as well as query it. Therefore this packer module gives a lot
+  # of class methods and mirrored instance methods that pack various types of objects. The instance methods
+  # aggregate all of the attachments and externals that need to be mapped back to the base object after they 
+  # are saved. The class methods return an array with the packaging in the first element and the attachment
+  # and externals in subsequent elements
+  class Translator 
+    attr_accessor :base_object, :base_id
+    
+    # PACKING ---------------------------------------------------------------------------------------
+    # ===============================================================================================
+    attr_writer :externals, :attachments 
+    
+    # Hash-like object that gathers all the externally saved aquatic objects. Pattern for storage is
+    #   external_object => 'pack_path_to_object'
+    # where the string 'pack_path_to_object' gets instance evaled in order to update the id in the pack
+    # after a new external is saved
+    # @api private
+    def externals
+      @externals ||= {}
+    end
+    
+    # An array of attachments that have to be stored by the base object
+    # @api private
+    def attachments
+      @attachments ||= []
+    end    
+    
+    # Although most of what the translator does happens via class level methods, instantiation happens 
+    # to maintain a reference to the base object when packing/saving externals and attachments. It is 
+    # also needed in the unpack process to locate attachments.
+    #
+    # @param [Aquatic Object]
+    #
+    # @api private
+    def initialize( base_object, base_id=nil )
+      load_base( base_object, base_id )
+    end 
+    
+    # Method used by initialized and reload_object to set necessary base object data
+    def load_base( base_object, base_id=nil)
+      self.base_object = base_object
+      self.base_id = base_object.id || base_id
+    end  
+    
+    # This is a wrapper method that takes the a class method and aggregates externals and attachments
+    # @api private
+    def pack
+      rat = yield 
+      self.externals.merge!( rat.externals )
+      self.attachments += rat.attachments
+      rat.pack
+    end  
+    
+    # Packs the ivars for a given object.  
+    #
+    # @param Object to pack 
+    # @param [String] path to this particular object within the parent object
+    # @return [Mash] Indifferent hash that is the data/metadata deconstruction of an object.
+    #
+    # @api private
+    def self.pack_ivars( obj, path='' )
+      path = "#{path}['ivars']"
+      rat = Rat.new
+      vars = obj.respond_to?(:_storable_attributes) ? obj._storable_attributes : obj.instance_variables
+      vars.each do |ivar_name| 
+        ivar = obj.instance_variable_get( ivar_name ) 
+        ivar_path = path + "['#{ivar_name}']" 
+        if ivar
+          if ivar == obj # self referential TODO: this will only work direct descendants :(
+            ivar_rat = pack_to_stub( ivar, ivar_path )
+            rat.hord( ivar_rat, ivar_name ) 
+          else   
+            ivar_rat = pack_object( ivar, ivar_path )
+            rat.hord( ivar_rat, ivar_name )
+          end
+        end         
+      end
+      rat
+    end
+    
+    # The instance version is wrapped by the #pack method. It otherwise performs the class method 
+    def pack_ivars( obj, path='' )
+      pack { self.class.pack_ivars( obj ) }
+    end
+    
+    # Packs an object into data and meta data. Works recursively sending out to array, hash, etc.  
+    # object packers, which send their values back to _pack_object
+    #
+    # @param Object to pack 
+    # @param [String] path, so that unsaved externals can find and set their id after creation
+    # @return [Mash] Indifferent hash that is the data/metadata deconstruction of an object.
+    #
+    # @api private  
+    def self.pack_object( obj, path='' )
+      klass = obj.class
+      if obj.respond_to?(:to_aqua) # probably requires special initialization not just ivar assignment
+        obj.to_aqua( path )
+      elsif obj.aquatic? 
+        if obj._embedded? || path == ''
+          pack_vanilla( obj, path )
+        else
+          pack_to_stub( obj, path)
+        end
+      else
+        pack_vanilla( obj, path )
+      end    
+    end
+    
+    # The instance version is wrapped by the #pack method. It otherwise performs the class method 
+    def pack_object( obj, path='' )
+      pack { self.class.pack_object( obj ) }
+    end
+    
+    # Packs the an object requiring no initialization.  
+    #
+    # @param Object to pack
+    # @return [Mash] Indifferent hash that is the data/metadata deconstruction of an object.
+    #
+    # @api private  
+    def self.pack_vanilla( obj, path='' )
+      rat = Rat.new( { 'class' => obj.class.to_s } ) 
+      ivar_rat = pack_ivars( obj, path )
+      rat.hord( ivar_rat, 'ivars' ) unless ivar_rat.pack.empty?
+      rat
+    end 
+    
+    # The instance version is wrapped by the #pack method. It otherwise performs the class method 
+    def pack_vanilla( obj, path='' )
+      pack { self.class.pack_vanilla( obj ) }
+    end
+    
+     
+    # Packs the stub for an externally saved object.  
+    #
+    # @param Object to pack
+    # @param [String] path to this part of the object
+    # @return [Mash] Indifferent hash that is the data/metadata deconstruction of an object.
+    #
+    # @api private    
+    def self.pack_to_stub( obj, path='' )
+      rat = Rat.new( {'class' => 'Aqua::Stub'} ) 
+      stub_rat = Rat.new({'class' => obj.class.to_s, 'id' => obj.id || '' }, {obj => path} )
+      # deal with cached methods
+      unless (stub_methods = obj._stubbed_methods).empty?
+        stub_rat.pack['methods'] = {}
+        stub_methods.each do |meth|
+          meth = meth.to_s
+          method_rat = pack_object( obj.send( meth ) )
+          stub_rat.hord( method_rat, ['methods', "#{meth}"])
+        end    
+      end
+      rat.hord( stub_rat, 'init' )
+    end
+    
+    # The instance version is wrapped by the #pack method. It otherwise performs the class method 
+    def pack_to_stub( obj, path='' )
+      pack { self.class.pack_to_stub( obj ) }
+    end  
+    
+    # def pack_singletons
+    #   # TODO: figure out 1.8 and 1.9 compatibility issues. 
+    #   # Also learn the library usage, without any docs :(
+    # end
+                 
+    # Rat class is used by the translators packing side and aggregates methods for merging
+    # packed representation, externals and attachments
+    class Rat 
+      attr_accessor :pack, :externals, :attachments
+      def initialize( pack=Mash.new, externals=Mash.new, attachments=[] )
+        self.pack = pack
+        self.externals = externals
+        self.attachments = attachments
+      end
+    
+      # merges the two rats
+      def eat( other_rat )
+        if self.pack.respond_to?(:keys) 
+          self.pack.merge!( other_rat.pack )
+        else
+          self.pack << other_rat.pack  # this is a special case for array init rats
+        end    
+        self.externals.merge!( other_rat.externals )
+        self.attachments += other_rat.attachments 
+        self
+      end
+    
+      # outputs and resets the accessor
+      def barf( accessor )
+        case accessor
+        when :pack, 'pack'
+          meal = self.pack
+          self.pack = {}
+        when :externals, 'externals'  
+          meal = self.externals
+          self.externals = {}  
+        else
+          meal = self.attachments
+          self.attachments = []
+        end    
+        meal
+      end
+    
+      def hord( other_rat, index)
+        if [String, Symbol].include?( index.class ) 
+          self.pack[index] = other_rat.barf(:pack) 
+        else # for nested hording
+          eval_string = index.inject("self.pack") do |result, element|
+            element = "'#{element}'" if element.class == String
+            result += "[#{element}]" 
+          end 
+          value = other_rat.barf(:pack)
+          instance_eval "#{eval_string} = #{value.inspect}"
+        end      
+        self.eat( other_rat ) 
+        self
+      end
+    
+      def ==( other_rat ) 
+        self.pack == other_rat.pack && self.externals == other_rat.externals && self.attachments == other_rat.attachments
+      end    
+    end
+    
+    # PACKING ---------------------------------------------------------------------------------------
+    # ===============================================================================================
+    def self.classes
+      @classes ||= {}
+    end  
+    
+    def self.get_class( class_str )
+      classes[class_str] ||= class_str.constantize  if class_str
+    end 
+    
+    def unpack_object( doc, opts=Opts.new ) 
+      opts.base_object  = self.base_object
+      opts.base_id      = self.base_object.id || self.base_id
+      self.class.unpack_object( doc, opts )
+    end  
+    
+    def self.unpack_object( doc, opts=Opts.new )
+      if doc.respond_to?(:from_aqua)
+        doc.from_aqua # these are basic types, like nil, strings, true/false, or symbols
+      else 
+        obj = new_from_doc( doc, opts )
+        
+        # mixin the id and rev
+        if obj.aquatic? && !obj._embedded?
+          obj.id = doc.id if doc.id
+          obj._rev = doc.rev if doc.rev
+        end   
+        
+        unpack_ivars( obj, doc, opts )
+        obj  
+      end    
+    end
+    
+    def self.new_from_doc( doc, opts  )
+      klass = get_class( doc['class'] )
+      obj = if (init = doc['init']) &&  klass.respond_to?( :aqua_init )
+        klass.aqua_init( init, opts )
+      else
+        klass.new   
+      end 
+    end
+    
+    def reload_from_init( doc )
+      if init = doc['init']
+        raise NotImplementedError, "Class #{base_object.class} does not implement a #replace method and can't be reloaded" unless base_object.respond_to?( :replace )
+        init_unpacked = unpack_object( {'class' => init.class.to_s, 'init' => init } ) 
+        base_object.replace( init_unpacked )
+      end
+      base_object 
+    end
+    
+    def unpack_ivars( doc )
+      opts = Opts.new
+      opts.base_object  = self.base_object
+      opts.base_id      = self.base_object.id || self.base_id
+      self.class.unpack_ivars( base_object, doc, opts )
+    end    
+     
+    
+    def self.unpack_ivars( obj, doc, opts ) 
+      # add the ivars  
+      if ivars = doc['ivars']
+        ivars.each do |ivar_name, ivar_hash|
+          opts.path += "#{ivar_name}"
+          unpacked_ivar = unpack_object( ivar_hash, opts ) 
+          obj.instance_variable_set( ivar_name, unpacked_ivar )
+        end  
+      end   
+    end
+    
+    def reload_object( obj, doc )
+      load_base( obj ) # loads this object as the base for the translator
+      reload_from_init( doc ) 
+      # todo: clear all non-hidden ivars too 
+      unpack_ivars( doc )
+      base_object._rev = doc.rev if doc.rev
+    end
+    
+    class Opts 
+      attr_accessor :base_object 
+      attr_accessor :base_id
+      attr_writer   :path
+      
+      def path
+        @path ||= ''
+      end  
+    end  
+    
+  end # Translator   
+end # Aqua   

data/lib/aqua/object/unpack.rb

@@ -4,7 +4,7 @@ module Aqua::Unpack
     klass.class_eval do
       extend ClassMethods
       include InstanceMethods
-    end  
+    end
   end 
   
   module ClassMethods
@@ -14,240 +14,39 @@ module Aqua::Unpack
     # 
     # @api public 
     def load( id ) 
-      instance = new
-      instance.id = id
-      instance.reload
-      instance
+      doc = _get_store( id )
+      build( doc, id )
     end
+    
+    # Retrieves objects storage from its engine.
+    # @return [Storage]
+    # 
+    # @api private 
+    def _get_store( id )
+      doc = self::Storage.get( id )
+      raise ArgumentError, "#{self} with id of #{doc_id} was not found" unless doc
+      doc 
+    end
+     
+    # Creates a new object from the doc; It is used by queries which return a set of docs.
+    # Also used by load to do the same thing ...
+    # @param [Document, Hash, Mash] converted object
+    def build( doc, id=nil )
+      translator = Aqua::Translator.new( new, id )
+      translator.unpack_object( doc ) 
+    end    
   end
   
   module InstanceMethods
-    # Reloads database information into the object.
-    # @param [optional true, false] Default is true. If true the exceptions will be swallowed and 
-    #   false will be returned. If false, then any exceptions raised will stop the show.
-    # @return [Object, false] Will return false or raise error on failure and self on success.
-    #
-    # @api public
-    def reload( mask_exceptions = true ) 
-      if id.nil?
-        if mask_exceptions
-          false
-        else
-          raise ObjectNotFound, "#{self.class} instance must have an id to be reloaded"
-        end    
-      else
-        begin
-          _reload
-        rescue Exception => e 
-          if mask_exceptions
-            false
-          else 
-            raise e
-          end    
-        end      
-      end  
-    end 
-    
     # Reloads database information into the object, and raises an error on failure.
     # @return [Object] Will return raise error on failure and return self on success.
     #
     # @api public
-    def reload!
-      reload( false )
-    end  
-    
-    private 
-      # Actual mechanism for reloading an object from stored data.
-      # @return [Object] Will return raise error on failure and return self on success.
-      #
-      # @api private
-      def _reload
-        _get_store
-        _unpack
-        _clear_store
-        self
-      end
-      
-      # Retrieves objects storage from its engine.
-      # @return [Storage]
-      # 
-      # @api private
-      def _get_store
-        # this is kind of klunky, should refactor
-        self._store = self.class::Storage.new(:id => self.id).retrieve
-      end
-      
-      # Unpacks an object from hash representation of data and metadata
-      # @return [Storage]
-      # @todo Refactor to move more of this into individual classes
-      #
-      # @api private
-      def _unpack
-        if init = _unpack_initialization( _store )
-          replace( init ) 
-        end
-        if ivars = _store[:ivars]
-          _unpack_ivars( self, ivars )
-        end    
-      end 
-      
-      # Makes @_store nil to converve on memory
-      #
-      # @api private
-      def _clear_store
-        @_store = nil
-      end  
-      
-      # Unpacks an object's instance variables
-      # @todo Refactor to move more of this into individual classes
-      #
-      # @api private
-      def _unpack_ivars( obj, data ) 
-        data.each do |ivar_name, data_package|
-          unpacked = if data_package.class == String
-            data_package
-          else
-            _unpack_object( data_package )
-          end
-          obj.instance_variable_set( ivar_name, unpacked )
-        end  
-      end    
-      
-      # Unpacks an the initialization object from a hash into a real object.
-      # @return [Object] Generally a hash, array or string
-      # @todo Refactor to move more of this into individual classes
-      #
-      # @api private
-      def _unpack_initialization( obj )
-        if init = obj[:init] 
-          init_class = init.class
-          if init_class == String
-            if init.match(/\A\/STUB_(\d*)\z/)
-              _unpack_stub( $1.to_i )
-            elsif init.match(/\A\/FILE_(.*)\z/) 
-              _unpack_file( $1, obj )
-            else    
-              init
-            end  
-          elsif init.class == Array 
-            _unpack_array( init )
-          else
-            _unpack_hash( init )
-          end    
-        end 
-      end
-      
-      # Retrieves and unpacks a stubbed object from its separate storage area
-      # @return [Aqua::Stub] Delegate object for externally saved class
-      # @param [Fixnum] Array index for the stub details, garnered from the key name
-      #
-      # @api private
-      def _unpack_stub( index ) 
-        hash = _store[:stubs][index] 
-        Aqua::Stub.new( hash ) 
-      end 
-      
-      # Retrieves and unpacks a stubbed object from its separate storage area
-      # @param [String] File name, and attachment id
-      # @return [Aqua::FileStub] Delegate object for file attachments
-      #
-      # @api private
-      def _unpack_file( name, obj )
-        hash = { 
-          :parent => self, 
-          :id => name,
-          :methods => obj[:methods] 
-        } 
-        Aqua::FileStub.new( hash ) 
-      end    
-       
-      # Unpacks an Array. 
-      # @return [Object] Generally a hash, array or string
-      # @todo Refactor ?? move more of this into support/initializers Array
-      #
-      # @api private
-      def _unpack_array( obj ) 
-        arr = [] 
-        obj.each do |value|
-          value = _unpack_object( value ) unless value.class == String
-          arr << value
-        end  
-        arr
-      end
-      
-      # Unpacks a Hash. 
-      # @return [Object] Generally a hash, array or string
-      # @todo Refactor ?? move more of this into support/initializers Hash
-      #
-      # @api private
-      def _unpack_hash( obj )
-        hash = {}
-        obj.each do |raw_key, value|
-          value = _unpack_object( value ) unless value.class == String
-          if raw_key.match(/\A(:)/)
-            key = raw_key.gsub($1, '').to_sym
-          elsif raw_key.match(/\A\/OBJECT_(\d*)\z/) 
-            key = _unpack_object( self._store[:keys][$1.to_i] )
-          else 
-            key = raw_key
-          end  
-          hash[key] = value
-        end
-        hash  
-      end    
-      
-      # The real workhorse behind object construction: it recursively rebuilds objects based on 
-      # whether the passed in object is an Array, String or a Hash (true/false too now). 
-      # A hash that has the class key 
-      # is an object representation. If it does not have a hash key then it is an ordinary hash.
-      # An array will either have strings or object representations values.
-      #
-      # @param [Hash, Mash] Representation of the data in the aqua meta format
-      # @return [Object] The object represented by the data
-      # 
-      # @api private
-      def _unpack_object( store_pack )
-        package_class = store_pack.class 
-        if package_class == String || store_pack == true || store_pack == false
-          store_pack
-        elsif package_class == Array 
-          _unpack_array( store_pack )  
-        else # package_class == Hash -or- Mash
-          if store_pack['class']
-            # Constantize the objects class
-            obj_class = store_pack['class'].constantize rescue nil
-            
-            # build from initialization 
-            init = _unpack_initialization( store_pack )
-            return_object = if init
-              [Aqua::Stub, Aqua::FileStub].include?( obj_class ) ? init : obj_class.aqua_init( init )
-            end
-            
-            # Build uninitialized object
-            if return_object.nil?
-              if obj_class
-                return_object = obj_class.new
-              else 
-                # should log an error internally
-                return_object = OpenStruct.new
-              end
-            end
-            
-            # add the ivars
-            if ivars = store_pack['ivars'] 
-              ivars.delete('@table') if obj_class.ancestors.include?( OpenStruct )
-              _unpack_ivars( return_object, ivars )
-            end
-                   
-            return_object 
-          else # not a packaged object, just a hash, so unpack
-            _unpack_hash( hash )
-          end    
-        end    
-             
-      end  
-            
-    public  
+    def reload 
+      doc = self.class._get_store( id )
+      _translator.reload_object( self, doc )
+      self
+    end 
   end
 
 end