datamapper 0.1.1 → 0.2.0

data/lib/data_mapper/callbacks.rb

@@ -1,16 +1,62 @@
 module DataMapper
   
+  # CallbacksHelper adds a class-method ClassMethods#callbacks
+  # when included in a class, and defines short-cut class-methods to
+  # add delegates to callbacks for the built-in Callbacks::EVENTS.
+  module CallbacksHelper
+    
+    # The ::included callback extends the included class with a
+    # ::callbacks method, and sets up helper methods for the standard
+    # events declared in Callbacks::EVENTS.
+    def self.included(base)
+      base.extend(ClassMethods)
+      
+      # Declare helpers for the standard EVENTS
+      Callbacks::EVENTS.each do |name|
+        base.class_eval <<-EOS
+          def self.#{name}(string = nil, &block)
+            if string.nil?
+              callbacks.add(:#{name}, block)
+            else
+              callbacks.add(:#{name}, string)
+            end
+          end
+        EOS
+      end
+    end
+    
+    # Defines class-methods for the class that CallbacksHelper is
+    # included in.
+    module ClassMethods
+      
+      # Provides lazily initialized access to a Callbacks instance.
+      def callbacks
+        @callbacks || ( @callbacks = DataMapper::Callbacks.new )
+      end
+    end
+  end
+  
+  # Callbacks is a collection to assign and execute blocks of code when
+  # hooks throughout the DataMapper call Callbacks#execute. A set of the
+  # standard callbacks is declared in the Callbacks::EVENTS array.
   class Callbacks
   
+    # These are a collection of default callbacks that are hooked
+    # into the DataMapper. You're free to add your own events just by
+    # calling #add, but you'll have add the appropriate hooks into the
+    # system to actually execute them yourself.
     EVENTS = [
       :before_materialize, :after_materialize,
       :before_save, :after_save,
       :before_create, :after_create,
       :before_update, :after_update,
       :before_destroy, :after_destroy,
-      :before_validate, :after_validate
+      :before_validation, :after_validation
       ]
-      
+    
+    # Initializes an internal Hash that ensures callback names are always
+    # of type Symbol, and assigns an Array to store your delegating code
+    # when the callback is looked-up by name.
     def initialize
       @callbacks = Hash.new do |h,k|
         raise 'Callback names must be Symbols' unless k.kind_of?(Symbol)
@@ -18,32 +64,33 @@ module DataMapper
       end
     end
     
-    alias ruby_method_missing method_missing
-    def method_missing(sym, *args)
-      if EVENTS.include?(sym)
-        self.class.send(:define_method, sym) { @callbacks[sym] }
-        return send(sym)
-      elsif sym.to_s =~ /^execute_(\w+)/ && EVENTS.include?($1.to_sym)
-        return execute(args.first, $1.to_sym)
-      end
-      
-      super
-    end
-    
-    def execute(name, instance)
-      @callbacks[name].each do |callback|
-        if callback.kind_of?(String)
-          instance.instance_eval(callback)
-        else
-          instance.instance_eval(&callback)
+    # Executes a given callback and returns TRUE or FALSE depending on the
+    # return value of the callbacks. All callbacks must return successfully
+    # in order for the call to #execute to return TRUE. Callbacks always
+    # execute against an +instance+. You may pass  additional arguments
+    # which will in turn be passed to any Proc objects assigned to a specific
+    # callback. Strings assigned to callbacks do not accept parameters.
+    # They are instance-eval'ed instead. When the callback is a Symbol,
+    # it is sent to the instance under the assumption it is a method call.
+    def execute(name, instance, *args)
+      @callbacks[name].all? do |callback|
+        case callback
+        when String then instance.instance_eval(callback)
+        when Proc then callback[instance, *args]
+        when Symbol then instance.send(callback, *args)
+        else raise ''
         end
       end
     end
     
-    def add(name, string = nil, &block)
-      callback = send(name)
-      raise ArgumentError.new("You didn't specify a callback in either string or block form.") if string.nil? && block.nil?
-      callback << (string.nil? ? block : string)
+    # Asign delegating code to a callback. The +block+ parameter
+    # can be a Proc object, a String which will be eval'ed when
+    # the callback is executed, or a Symbol, which will be sent to
+    # the instance executed against (as a method call).
+    def add(name, block)
+      callback = @callbacks[name]
+      raise ArgumentError.new("You didn't specify a callback in String, Symbol or Proc form.") if block.nil?
+      callback << block
     end
   end
   

data/lib/data_mapper/{session.rb → context.rb}

@@ -2,7 +2,7 @@ require 'data_mapper/identity_map'
 
 module DataMapper
   
-  class Session
+  class Context
       
     class MaterializationError < StandardError
     end
@@ -17,7 +17,7 @@ module DataMapper
       @identity_map || ( @identity_map = IdentityMap.new )
     end
     
-    def first(klass, *args, &b)
+    def first(klass, *args)
       id = nil
       options = nil
       
@@ -44,32 +44,40 @@ module DataMapper
       @adapter.load(self, klass, options)
     end
     
+    def count(klass, options = {})
+      @adapter.count(klass, options)
+    end
+    
     def save(instance)
       @adapter.save(self, instance)
     end
     
     def destroy(instance)
-      @adapter.delete(instance, :session => self)
+      @adapter.delete(self, instance)
     end
     
     def delete_all(klass)
-      @adapter.delete(klass, :session => self)
+      @adapter.delete(self, klass)
     end
     
     def truncate(klass)
-      @adapter.delete(klass, :truncate => true, :session => self)
+      @adapter.truncate(self, klass)
     end
     
     def create_table(klass)
-      @adapter[klass].create!
+      @adapter.create_table(klass)
     end
     
     def drop_table(klass)
-      @adapter[klass].drop!
+      @adapter.drop(self, klass)
     end
     
     def table_exists?(klass)
-      @adapter[klass].exists?
+      @adapter.table_exists?(klass)
+    end
+    
+    def execute(*args)
+      @adapter.execute(*args)
     end
     
     def query(*args)      
@@ -80,6 +88,10 @@ module DataMapper
       @adapter.schema
     end
     
+    def table(klass)
+      @adapter.table(klass)
+    end
+    
     def log
       @adapter.log
     end

data/lib/data_mapper/database.rb

@@ -1,5 +1,6 @@
 require 'logger'
-require 'data_mapper/session'
+require 'data_mapper/context'
+require 'data_mapper/adapters/abstract_adapter'
 
 # Delegates to DataMapper::database.
 # Will not overwrite if a method of the same name is pre-defined.
@@ -9,17 +10,24 @@ end unless methods.include?(:database)
 
 module DataMapper
   
-  # Block Syntax:
-  #   Pushes the named database onto the context-stack, 
-  #   yields a new session, and pops the context-stack.
-  # Non-Block Syntax:
-  #   Returns the current session, or if there is none,
-  #   a new Session.
-  def self.database(name = :default)
+  # ===Block Syntax:
+  # Pushes the named database onto the context-stack, 
+  # yields a new session, and pops the context-stack.
+  #
+  #   results = DataMapper.database(:second_database) do |current_context|
+  #     ...
+  #   end
+  #
+  # ===Non-Block Syntax:
+  # Returns the current session, or if there is none,
+  # a new Session.
+  #
+  #   current_database = DataMapper.database
+  def self.database(name = :default) # :yields: current_context
     unless block_given?
-      Database.context.last || Session.new(Database[name].adapter)
+      Database.context.last || Context.new(Database[name].adapter)
     else
-      Database.context.push(Session.new(Database[name].adapter))
+      Database.context.push(Context.new(Database[name].adapter))
       result = yield(Database.context.last)
       Database.context.pop
       result
@@ -30,70 +38,193 @@ module DataMapper
     attr_accessor :options
   end
   
+  # The Database class allows us to setup a default database for use throughout our applications
+  # or allows us to setup a collection of databases to use.
+  #
+  # === Example
+  # ==== To setup a default database
+  #   DataMapper::Database.setup({
+  #    :adapter  => 'mysql'
+  #    :host     => 'localhost'
+  #    :username => 'root'
+  #    :password => 'R00tPaswooooord'
+  #    :database => 'selecta_development'
+  #   })
+  #
+  # ==== To setup a named database
+  #   DataMapper::Database.setup(:second_database, {
+  #    :adapter  => 'postgresql'
+  #    :host     => 'localhost'
+  #    :username => 'second_user'
+  #    :password => 'second_password'
+  #    :database => 'second_database'
+  #   })
+  #
+  #
+  # ==== Working with multiple databases (see #DataMapper::database)
+  #   DataMapper.database(:second_database) do
+  #     ...
+  #   end
+  #
+  #   DataMapper.database(:default) do
+  #     ...
+  #   end
+  #
+  # or even...
+  #
+  #   #The below variables still hold on to their database sessions.
+  #   #So no confusion happens when passing variables around scopes.
+  #
+  #   DataMapper.database(:second_database) do
+  #
+  #     animal = Animal.first
+  #
+  #     DataMapper.database(:default) do
+  #       Animal.new(animal).save
+  #     end # :default database
+  #
+  #   end # :second_database
   class Database
     
     @databases = {}
     @context = []
     
+    # Allows you to access any of the named databases you have already setup.
+    #
+    #   default_db = DataMapper::Database[:default]
+    #   second_db = DataMapper::Database[:second_database]
     def self.[](name)
       @databases[name]
     end
     
+    # Returns the array of Database sessions currently being used
+    #
+    # This is what gives us thread safety, boys and girls
     def self.context
       @context
     end
     
-    def self.setup(name = :default, &initializer)
+    # Setup creates a database and sets all of your properties for that database.
+    # Setup looks for either a hash of options passed in to the database or a symbolized name
+    # for your database, as well as it's hash of parameters
+    #
+    # If no options are passed, an ArgumentException will be raised.
+    #   
+    #   DataMapper::Database.setup(name = :default, options_hash)
+    #
+    #   DataMapper::Database.setup({
+    #    :adapter  => 'mysql'
+    #    :host     => 'localhost'
+    #    :username => 'root'
+    #    :password => 'R00tPaswooooord'
+    #    :database => 'selecta_development'
+    #   })
+    #
+    #
+    #   DataMapper::Database.setup(:named_database, {
+    #    :adapter  => 'mysql'
+    #    :host     => 'localhost'
+    #    :username => 'root'
+    #    :password => 'R00tPaswooooord'
+    #    :database => 'selecta_development'
+    #   })
+    
+    def self.setup(*args)
+      
+      name, options = nil
+      
+      if (args.nil?) || (args[1].nil? && args[0].class != Hash)
+        raise ArgumentError.new('Database cannot be setup without at least an options hash.')
+      end
+      
+      if args.size == 1
+        name, options = :default, args[0]
+      elsif args.size == 2
+        name, options = args[0], args[1]
+      end        
+      
       current = self.new(name)
-      current.instance_eval(&initializer)
+      
+      current.single_threaded = false if options[:single_threaded] == false
+      
+      options.each_pair do |k,v|
+        current.send("#{k}=", v)
+      end
+      
       @databases[name] = current
     end
     
+    # Creates a new database object with the name you specify, and a default set of options.
+    #
+    # The default options are as follows:
+    #   {:single_threaded => true, :host => 'localhost', :database => nil, :username => 'root', :password => '', :adapter = nil }
     def initialize(name)
       @name = name
-    end
-    
-    attr_reader :name
-    
-    def adapter(value = nil)
-      return @adapter if value.nil?
-      
-      raise ArgumentError.new('The adapter is readonly after being set') unless @adapter.nil?
       
-      require "data_mapper/adapters/#{String::memoized_underscore(value)}_adapter"
-      adapter_class = Adapters::const_get(Inflector.classify(value) + "Adapter")
+      @single_threaded = true
+      @adapter = nil
+      @host = 'localhost'
+      @database = nil
+      @schema_search_path = nil
+      @username = 'root'
+      @password = ''
+      @index_path = (Dir::pwd + "/indexes")
       
-      @adapter = adapter_class.new(self)
+      @log_level = Logger::WARN
+      @log_stream = nil
     end
     
-    def host(value = nil); value.nil? ? (@host || 'localhost') : @host = value end
-    def database(value = nil); value.nil? ? @database : @database = value end
-    def username(value = nil); value.nil? ? @username : @username = value end
-    def password(value = nil); value.nil? ? (@password || '') : @password = value end
+    attr_reader :name, :adapter
+    attr_writer :single_threaded
+    attr_accessor :host, :database, :schema_search_path, :username, :password, :log_stream, :log_level, :index_path, :socket
     
-    # single_threaded mode is disabled by default currently since it's buggy.
-    def single_threaded(value = nil); value.nil? ? (@single_threaded.nil? ? @single_threaded = false : @single_threaded) : @single_threaded = value end
+    # Returns true or false
+    #
+    # NOTE: single_threaded is true unless explicitly set to false.
+    def single_threaded?
+      @single_threaded
+    end
     
-    def log(value = nil)
-      @log = value unless value.nil?
-
-      if @log.nil?
-        @log = log_stream.nil? ? Logger.new(nil) : Logger.new(log_stream, File::WRONLY | File::APPEND | File::CREAT)
-        @log.level = log_level || Logger::WARN
-        at_exit { @log.close }
+    # Allows us to set the adapter for this database object. It can only be set once, and expects two types of values.
+    #
+    # You may pass in either a class inheriting from DataMapper::Adapters::AbstractAdapter
+    # or pass in a string indicating the type of adapter you would like to use.
+    #
+    # To create your own adapters, create a file in data_mapper/adapters/new_adapter.rb that inherits from AbstractAdapter
+    #
+    #   database.adapter=("postgresql")
+    def adapter=(value)
+      if @adapter
+        raise ArgumentError.new('The adapter is readonly after being set')
       end
       
-      @log
-    end
-    
-    def log_level(value = nil)
-      return @log_level if value.nil?
-      @log_level = value
+      if value.is_a?(DataMapper::Adapters::AbstractAdapter)
+        @adapter = value
+      elsif value.is_a?(Class)
+        @adapter = value.new(self)
+      else
+        begin
+          require "data_mapper/adapters/#{Inflector.underscore(value)}_adapter"
+        rescue LoadError
+          require "#{Inflector.underscore(value)}_adapter"
+        end
+        adapter_class = Adapters::const_get(Inflector.classify(value) + "Adapter")
+      
+        @adapter = adapter_class.new(self)
+      end
     end
     
-    def log_stream(value = nil)
-      return @log_stream if value.nil?
-      @log_stream = value
+    # Default Logger from Ruby's logger.rb
+    def log
+      @log = Logger.new(@log_stream, File::WRONLY | File::APPEND | File::CREAT)
+      @log.level = @log_level
+      at_exit { @log.close }
+      
+      class << self
+        attr_reader :log
+      end
+      
+      return @log
     end
     
   end