aqua 0.1.6

data/VERSION

@@ -0,0 +1 @@
+0.1.6

data/lib/aqua.rb

@@ -0,0 +1,101 @@
+# DEPENDENCIES -------------------------------------
+# require gems
+require 'rubygems' 
+require 'ruby2ruby'
+require 'mime/types'
+# Pick your json poison. Just make sure that in adds the JSON constant
+unless defined?(JSON)
+  begin
+    require 'json'
+  rescue LoadError
+    raise LoadError, "JSON constant not found. Please install a JSON library"
+  end  
+end
+# There is also a dependency on the http_client of your choosing. Currently only ...
+# require 'rest_client'
+# It is required when a libarary is configured. If the library is not configured then it will 
+# automatically load the default: rest_client
+
+# standard libraries
+require 'cgi'
+require 'time'
+require 'ostruct'
+require 'tempfile'
+
+# require local libs
+$:.unshift File.join(File.dirname(__FILE__))
+  # monkey pathches
+require 'aqua/support/mash'
+require 'aqua/support/string_extensions'
+  # storage 
+require 'aqua/store/storage' 
+  # object methods
+require 'aqua/object/tank'
+  # a little more monkey patching for object packaging
+require 'aqua/support/initializers'
+
+
+# LIBRARY SETUP -----------------------------------
+module Aqua
+  class ObjectNotFound < IOError; end
+  
+  # Loads the requested backend storage engine. Used early on in configuration. 
+  # If not declared in configuration, will be called automatically with default 
+  # engine, at runtime, when needed.
+  #
+  # @overload set_storage_engine( engine )
+  #   Loads an Aqua internal library.
+  #   @param [String] CamelCase string defining the overarching engine type
+  # @overload set_storage_engine( engine_details )
+  #   Loads any engine provided a path to the self-loading library and the module full name
+  #   @param [Hash] options that describe how to find the external library
+  #   @option engine_details [String] :require The path or gem name used in a require statement
+  #   @option engine_details [String] :module String with the full module name
+  # @return [TrueClass] when successful. 
+  # @raise [ArgumentError] when argument is neither a Hash nor a String.
+  # 
+  # @example Internal library loading from a string
+  #   Aqua.set_storage_engine( "CouchDB" )
+  #
+  # @example External library loading from a gem. :module argument is the gem's module responsible for implementing the storage methods
+  #   Aqua.set_storage_engine( :require => 'my_own/storage_gem', :module => 'MyOwn::StorageGem::StorageMethods' )
+  #
+  # @example External library loading from a non-gem external library. 
+  #   Aqua.set_storage_engine( :require => '/absolute/path/to/library', :module => 'My::StorageLib::StorageMethods' )
+  #
+  # @api public
+  def self.set_storage_engine( engine="CouchDB" ) 
+    if engine.class == String
+      load_internal_engine( engine )
+      true
+    elsif engine.class == Hash
+      engine = Mash.new( engine )
+      require engine[:require]
+      include_engine( engine[:module] )
+      true
+    else
+      raise ArgumentError, 'engine must be a string relating to an internal Aqua library store, or a hash of values indicating where to find the external library'
+    end      
+  end
+  
+  # Loads an internal engine from a string
+  # @api private
+  def self.load_internal_engine( str )
+    underscored = str.underscore
+    require "aqua/store/#{underscored}/#{underscored}"
+    include_engine( "Aqua::Store::#{str}::StorageMethods" )
+  end
+  
+  # Loads an external engine from a hash of options. 
+  # @see Aqua#set_storage_engine for the public method that uses this internally
+  # @api private
+  def self.include_engine( str )
+    Aqua::Storage.class_eval do
+      include str.constantize
+    end
+  end       
+
+end # Aqua  
+
+# This is temporary until more engines are available!
+Aqua.set_storage_engine('CouchDB') # to initialize CouchDB

data/lib/aqua/object/config.rb

@@ -0,0 +1,43 @@
+module Aqua::Config
+  def self.included( klass ) 
+    # This per aquatic class storage class is used to maintain the storage specific options, 
+    # such as a particular database for the class. Otherwise, appeals directly to Aqua::Storage 
+    # for class methods will loose database and other class specific storage options
+    klass.class_eval "
+      class Storage < Aqua::Storage
+        def self.parent_class
+          '#{klass}'
+        end  
+      end
+    "
+    
+    klass.class_eval do
+      extend ClassMethods
+      configure_aqua
+      
+      hide_attributes :_aqua_opts
+    end   
+  end
+  
+  module ClassMethods 
+    def configure_aqua(opts={})
+      database = opts.delete(:database)
+      self::Storage.database = database
+      @_aqua_opts = Mash.new( _aqua_opts ).merge!(opts)
+    end
+    
+    def _aqua_opts
+      @_aqua_opts ||= _aqua_config_defaults
+    end   
+    
+    private
+      def _aqua_config_defaults
+        {
+          :database => nil, # Default is the same as the server. Everything is saved to the same db
+          :embed => false,  # options false, true, or :stub => [:attributes, :to_save, :in_the_other_object]
+        }
+      end
+    public   
+  end
+
+end   

data/lib/aqua/object/pack.rb

@@ -0,0 +1,306 @@
+# This module is responsible for packing objects into Storage Objects
+# The Storage Object is expected to be a Mash-Like thing (Hash with indifferent access).
+# It is the job of the storage engine to convert the Mash into the actual storage ivars.
+module Aqua
+  module Pack
+  
+    def self.included( klass ) 
+      klass.class_eval do
+        extend HiddenAttributes::ClassMethods
+        include HiddenAttributes::InstanceMethods
+        extend ClassMethods
+        include InstanceMethods
+      
+        unless instance_methods.include?( 'id=' ) || new.instance_variables.include?( '@id' )
+          attr_accessor :id
+        end
+      
+        hide_attributes :_store, :__pack, :id, :_rev 
+      end  
+    end
+  
+    module HiddenAttributes
+      def self.included( klass ) 
+        klass.class_eval do
+          extend ClassMethods
+          include InstanceMethods
+        end
+      end
+          
+      module ClassMethods
+        # Reader method for accessing hidden attributes. 
+        # @return [Array] containing strings representing instance variables
+        # @api private
+        def _hidden_attributes 
+          @_hidden_attributes ||= []
+        end
+      
+        # Used in class declaration to assign certain instance variables as not for persistance
+        # @param [Symbol] or [Array of Symbols] ivars 
+        # 
+        # @example
+        # class User 
+        #   include Aqua::Object
+        #   attr_accessor :username, :email, :password, :password_confirmation, :cryped_password, :salt
+        #   hide_attributes :password, :password_confirmation 
+        #   # ... lots more user code here ...
+        # end
+        # In this case it is useful for omitting sensitive information while persisting the object, but 
+        # maintaining the password and confirmation temporarily requires the use of instance variables.
+        def hide_attributes( *ivars )
+          ivars.each do |ivar|
+            raise ArgumentError, '' unless ivar.class == Symbol
+            _hidden_attributes << "@#{ivar}" unless _hidden_attributes.include?( "@#{ivar}" )
+          end  
+        end 
+      end # ClassMethods  
+     
+      module InstanceMethods 
+        # An array of instance variables that are not hidden.
+        # @return [Array] of names for instance variables
+        # 
+        # @api private
+        def _storable_attributes
+          (instance_variables||[]) - self.class._hidden_attributes
+        end 
+      end # InstanceMethods     
+    end   
+  
+    module ClassMethods 
+    end # ClassMethods
+  
+    module InstanceMethods
+      # TODO: option for transaction on children documents, all or nothing
+    
+      # Saves object; returns false on failure; returns self on success.
+      def commit 
+        _commit
+      end
+    
+      # Saves object and raises an error on failure
+      def commit!
+        _commit( false )
+      end
+    
+      # packs an object from it's Ruby state into a Hash-like object for storage. 
+      # @return [Storage]
+      #
+      # @api private
+      def _pack
+        class_name = self.class.to_s
+        self.__pack = Storage.new
+        self.__pack.id = @id if @id
+        self.__pack[:_rev] = _rev if _rev 
+        self.__pack[:keys] = []
+        self.__pack[:stubs] = [] 
+        self.__pack.merge!( _pack_object( self ) )
+        _pack_singletons
+        __pack
+      end
+    
+      # Details from configuration options for the objects class about embedability. 
+      # @return [true, false, Hash] If true then it should be embedded in the object at hand. 
+      #   If false, then it should be saved externally. If a hash, with the key :stub and a related
+      #   value that is an array of methods, then the object should be saved externally, 
+      #   with a few cached methods as defined in the array.
+      # 
+      # @api private
+      def _embed_me 
+        self.class._aqua_opts[:embed]
+      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
+      # @return [Mash] Indifferent hash that is the data/metadata deconstruction of an object.
+      #
+      # @api private
+      def _pack_object( obj ) 
+        klass = obj.class
+        if klass == String
+          obj
+        elsif obj.respond_to?(:to_aqua) # Types requiring initialization
+          obj.to_aqua( self )
+        elsif obj.aquatic? && obj != self
+          if obj._embed_me == true
+            obj._pack
+          else
+            _build_stub( obj ) 
+          end   
+        else # other object without initializations
+          _pack_vanilla( obj )
+        end     
+      end
+     
+      # Packs the ivars for a given object.  
+      #
+      # @param Object to pack
+      # @return [Mash] Indifferent hash that is the data/metadata deconstruction of an object.
+      #
+      # @api private
+      def _pack_ivars( obj )
+        return_hash = {}
+        vars = obj.respond_to?(:_storable_attributes) ? obj._storable_attributes : obj.instance_variables
+        vars.each do |ivar_name|
+          ivar = obj.instance_variable_get( ivar_name )
+          return_hash[ivar_name] = _pack_object( ivar ) unless ivar.nil?       
+        end
+        return_hash
+      end
+    
+      # Handles the case of an hash-like object with keys that are objects  
+      #
+      # @param Object to pack
+      # @return [Integer] Index of the object in the keys array, used by the hash packer to name the key
+      #
+      # @api private
+      def _build_object_key( obj )
+        index = self.__pack[:keys].length
+        self.__pack[:keys] << _pack_object( obj )
+        index # return key
+      end 
+      
+      # Adds an attachment to the __pack document. Before save the attachments are encoded into the doc  
+      #
+      # @param [String] filename used as the key/index
+      # @param [File, Tempfile] file to be attached
+      #
+      # @api semi-public
+      def _pack_file( filename, file )
+        __pack.attachments.add( filename, file )
+      end     
+           
+    
+      attr_accessor :_warnings 
+       
+      # Private/protected methods are all prefaced by an underscore to prevent
+      # clogging the object instance space. Some of the public ones above are too!
+      protected
+      
+        # __pack is an Storage object into which the object respresentation is packed
+        #
+        # _store is the current state of the storage of the object on CouchDB. It is used lazily
+        # and will be empty unless it is needed for unpacking or checking for changed data.
+        #
+        # _rev is needed for CouchDB store, since updates require the rev information. We could
+        # do without this accessor, but it would mean that an extra get request would have to be
+        # made with each PUT request so that the latest _rev could be obtained. 
+        #
+        attr_accessor :_store, :__pack, :_rev
+      
+      private
+      
+        def _commit( mask_exception = true ) 
+          result = true
+          begin
+            _pack
+            _save_to_store
+          rescue Exception => e
+            if mask_exception
+              result = false
+            else
+              raise e
+            end    
+          end
+          if result
+            self.id =   __pack.id
+            self._rev = __pack.rev
+            _clear_accessors
+            self
+          else
+            result
+          end    
+        end    
+       
+        # Object packing methods ------------
+      
+        # 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 _pack_vanilla( obj ) 
+          {
+            'class' => obj.class.to_s,
+            'ivars' => _pack_ivars( obj )
+          }
+        end
+      
+        # Packs the stub for an externally saved object.  
+        #
+        # @param Object to pack
+        # @return [Mash] Indifferent hash that is the data/metadata deconstruction of an object.
+        #
+        # @api private    
+        def _build_stub( obj )
+          index = self.__pack[:stubs].length 
+          stub = { :class => obj.class.to_s, :id => obj } 
+          # deal with cached methods
+          if obj._embed_me && obj._embed_me.keys && stub_methods = obj._embed_me[:stub]
+            stub[:methods] = {}
+            if stub_methods.class == Symbol || stub_methods.class == String
+              stub_method = stub_methods.to_sym 
+              stub[:methods][stub_method] = obj.send( stub_method )
+            else # is an array of values
+              stub_methods.each do |meth|
+                stub_method = meth.to_sym
+                stub[:methods][stub_method] = obj.send( stub_method )
+              end  
+            end    
+          end
+          # add the stub  
+          self.__pack[:stubs] << stub
+          # return a hash  
+          {'class' => 'Aqua::Stub', 'init' => "/STUB_#{index}"}
+        end 
+      
+        def _pack_singletons
+          # TODO: figure out 1.8 and 1.9 compatibility issues. 
+          # Also learn the library usage, without any docs :(
+        end    
+      
+        # Saves all self and nested object requiring independent saves
+        # 
+        # @return [Object, false] Returns false on failure and self on success.
+        #
+        # @api private
+        def _save_to_store
+          self._warnings = []
+          _commit_externals 
+          __pack.commit # TODO: need to add some error catching and roll back the external saves where needed
+        end
+      
+        # Saves nested object requiring independent saves. Adds warning messages to _warnings, when a save fails.
+        #
+        # @api private
+        def _commit_externals 
+          __pack[:stubs].each_with_index do |obj_hash, index|
+            obj = obj_hash[:id]
+            if obj.commit
+              obj_hash[:id] = obj.id
+            else
+              if obj.id
+                self._warnings << "Unable to save latest version of #{obj.inspect}, stubbed at index #{index}"
+                obj_hash[:id] = obj.id if obj.id 
+              else  
+                self._warnings << "Unable to save #{obj.inspect}, stubbed at index #{index}" 
+              end  
+            end    
+          end  
+        end 
+      
+        # clears the __pack and _store accessors to save on memory after each pack and unpack
+        # 
+        # @api private
+        def _clear_accessors
+          self.__pack = nil
+          self._store = nil
+        end
+              
+      public  
+    end # InstanceMethods     
+  end # Pack
+end # Aqua 
+