dm-core 0.9.2

data/CHANGELOG

@@ -0,0 +1,144 @@
+-- 0.1.0
+* Initial Public Release
+
+-- 0.1.1
+* Removed /lib/data_mapper/extensions
+* Moved ActiveRecordImpersonation into DataMapper::Support module
+* Moved CallbackHelper methods into DataMapper::Base class
+* Moved ValidationHelper into DataMapper::Validations module
+* Removed LoadedSet since it's not necessary for it to reference the Database, so it's nothing more than an array now; Replaced with Array
+* Modified data_mapper.rb to load DataMapper::Support::Enumerable
+* Modified example.rb and performance.rb to require 'lib/data_mapper' instead of modifying $LOADPATH
+* Created SqlAdapter base-class
+* Refactored MysqlAdapter to use SqlAdapter superclass
+* Refactored Sqlite3Adapter to use SqlAdapter superclass
+* Moved /lib/data_mapper/queries to /lib/data_mapper/adapters/sql/queries
+* Moved Connection, Result and Reader classes along with Coersion and Quoting modules to DataMapper::Adapters::Sql module
+* Moved DataMapper::Adapters::Sql::Queries to ::Commands
+* Moved Mappings to SqlAdapter
+* Added monolithic DeleteCommand
+* Added monolithic SaveCommand
+* Added TableExistsCommand
+* Moved save/delete logic out of Session
+* Added create-table functionality to SaveCommand
+* Cleaned up Session; #find no longer supported, use #all or #first
+* Moved object materialization into LoadCommand
+* Migrated Sqlite3Adapter::Commands
+* Added Session#query support back in
+* Removed Connection/Reader/Result classes
+* Set DataMapper::Base#key on load to avoid double-hit against Schema
+* Added DataMapper::Support::Struct for increased Session#query performance
+* Added AdvancedHasManyAssociation (preview status)
+* Added benchmarks comparing ActiveRecord::Base::find_by_sql with Session#query
+
+-- 0.2.0
+* AdvancedHasManyAssociation now functional for fetches
+* AdvancedHasManyAssociation renamed to HasNAssociation
+* HasManyAssociation refactored to use HasNAssociation superclass
+* Slight spec tweaks to accomodate the updates
+* HasOneAssociation refactored to use HasNAssociation superclass
+* Added HasAndBelongsToManyAssociation, using HasNAssociation as a basis; Need to add corresponding SQL generation code in AdvancedLoadCommand
+* Added spec for habtm query generation
+* HasNAssociation#foreign_key returns a DataMapper::Adapters::Sql::Mappings::Column instance instead of a raw String now
+* Added table, association, association_table and to_sql methods to HasNAssociation
+* Added associations_spec.rb
+* Added a forced table-recreation to spec_helper.rb so the tests could run with a clean version of the database, including any new columns added to the models
+* Added HasAndBelongsToManyAssociation#to_sql (all current specs pass now!)
+* Minor tweaks to Callbacks
+* Added CallbacksHelper to declare class-method ::callbacks on DataMapper::Base
+* Implemented before_validate and after_validate hooks in ValidationHelper
+* Minor documentation additions in callbacks.rb
+* Added callbacks_spec
+* Moved class-method declarations for built-in callbacks to the callbacks helper instead of DataMapper::Base
+* Renamed :before/after_validate callback to :before/after_validation to match ActiveRecord
+* Callbacks#add now accepts a Symbol which maps a callback to a method call on the targetted instance, also added a spec to verify this behavior
+* Documented callbacks.rb
+* Added DataMapper::Associations::Reference class
+* Documented DataMapper::Associations::Reference class
+* Upgraded BelongsToAssociation to new style
+* Added AssociationsSet to handle simple "last-in" for association bindings
+* Fixed extra spec loading
+* Added *Association#columns
+* Some refactoring in AdvancedLoadCommand regarding :include options
+* Added support for class-less Mappings::Table instances, with just a string name
+* HasAndBelongsToManyAssociation#join_table #left_foreign_key and #right_foreign_key reference actual Table or Column objects now
+* Added :shallow_include option for HABTM joins in AdvancedLoadCommand and corresponding spec
+* Added Commands::AdvancedConditions
+* Added ORDER, LIMIT, OFFSET and WHERE support to AdvancedLoadCommand
+* Renamed spec/has_many.rb to spec/has_many_spec.rb
+* Tweaked the loading of has_many relationships; big performance boost; got rid of an extra query
+* Added EmbeddedValue support, and accompanying spec
+* Fleshed out AdvancedConditions a bit; added conditions_spec.rb
+* Added more AdvancedConditions specs
+* Added Loader to handle multi-instanced rows
+* AdvancedLoadCommand replaced LoadCommand; down to 3 failing specs
+* All specs pass
+* Added :intercept_load finder option and accompanying spec
+* Modified :intercept_load block signature to |instance,columns,row|
+* HasAndBelongsToMany works, all specs pass
+* Fixed a couple bugs with keys; Added DataMapper::Base#key= method
+* Made DataMapper::Base#lazy_load! a little more flexible
+* Removed LoadCommand overwrites from MysqlAdapter
+* Default Database#single_threaded mode is true now
+* Removed MysqlAdapter#initialize, which only served to setup the connections, moved to SqlAdapter
+* Added SqlAdapter#create_connection and SqlAdapter#close_connection abstract methods
+* Added MysqlAdapter#create_connection and MysqlAdapter#close_connection concrete methods
+* Made SqlAdapter#connection a concrete method (instead of abstract), with support for single_threaded operation
+* Database#setup now takes a Hash of options instead of a block-initializer
+* Validation chaining should work for all association types
+* Save chaining should work for has_many associations
+* Added benchmarks for in-session performance to performance.rb
+* Removed block conditions; They're slower and don't offer any real advantages
+* Removed DeleteCommand
+* Removed SaveCommand
+* Removed TableExistsCommand
+* Session renamed to Context
+* Most command implementations moved to methods in SqlAdapter
+* Removed UnitOfWork module, instead moving a slightly refactored implementation into Base
+
+-- 0.2.1
+* Added :float column support
+* Added association proxies: ie: Zoo.first.exhibits.animals
+* Columns stored in SortedSet
+* Swig files are no longer RDOCed
+* Added :date column support
+* BUG: Fixed UTC issues with datetimes
+* Added #to_yaml method
+* Added #to_xml method
+* Added #to_json method
+* BUG: Fixed HasManyAssociation::Set#inspect
+* BUG: Fixed #reload!
+* BUG: Column copy for STI moved into Table#initialize to better handle STI with multiple mapped databases
+* BUG: before_create callbacks moved in the execution flow since they weren't guaranteed to fire before
+* Threading enhancements: Removed single_threaded_mode, #database block form adjusted for thread-safety
+* BUG: Fixed String#blank? when a multi-line string contained a blank line (thanks zapnap!)
+* Performance enhancements: (thanks wycats!)
+
+-- 0.2.2
+* Removed C extension bundles and log files from package
+
+-- 0.2.3
+* Added String#t for translation and overrides for default validation messages
+* Give credit where it's due: zapnap, not pimpmaster, submitted the String#blank? patch. My bad. :-(
+* MAJOR: Resolve issue with non-unique-hash values and #dirty?; now frozen original values are stored instead
+* Added Base#update_attributes
+* MAJOR: Queries are now passed to the database drivers in a parameterized fashion
+* Updated PostgreSQL driver and adapter to current
+
+-- 0.2.4
+* Bug fixes
+* Added paranoia
+
+-- 0.2.5
+* has_one bugfixes
+* Added syntax for setting CHECK-constraints directly in your properties (Postgres)
+* You can now set indexes with :index => true and :index => :unique
+* Support for composite indexes (thanks to Jeffrey Gelens)
+* Add composite scope to validates_uniqueness
+* Added private/protected properties
+* Remove HasOneAssociation, Make HasManyAssociation impersonate has_one relationships
+* Added #get method
+* Persistence module added, inheriting from DataMapper::Base no longer necessary
+
+-- 0.3.0
+* HasManyAssociation::Set now has a nil? method, so we can do stuff like cage.animal.nil?

data/FAQ

@@ -0,0 +1,74 @@
+:include:QUICKLINKS
+
+= FAQ
+
+=== So where's my :id column?
+
+DataMapper will NOT create an auto-incrementing <tt>:id</tt> key for you 
+automatically, so you'll need to either explicitly create one with
+
+  property :id, Serial
+
+You can choose to use a natural key by doing
+
+  property :slug, String, :key => true
+
+Remember, DataMapper supports multiple keys ("composite keys"), so if your
+model has two or more keys, no big deal
+
+  property :store_id, 	Integer, :key => true
+  property :invoice_id, Integer, :key => true
+
+=== How do I make a model paranoid?
+
+Create a property and make it a ParanoidDateTime or ParanoidBoolean type.
+
+  property :deleted_at, ParanoidDateTime
+  property :deleted, ParanoidBoolean
+
+All of your calls to <tt>##all()</tt>, <tt>##first()</tt> will be scoped 
+with <tt>:deleted_at => nil</tt> or <tt>:deleted => false</tt>. Plus, 
+you won't see deleted objects in your associations.
+
+=== Does DataMapper do Single Table Inheritance?
+
+This is what the Discriminator data-type is for:
+
+  class Person
+    include DataMapper::Resource
+    property :id, Serial
+    property :type, Discriminator ## other shared properties here
+  end
+
+  class Salesperson < Person; end
+
+You can claim a column to have the type <tt>Discriminator</tt> and DataMapper will
+automatically drop the class name of the inherited classes into that field of
+the data-store.
+
+=== How do I run my own commands?
+
+  repository.adapter.query("select * from users where clue > 0")
+  repository(:integration).adapter.query("select * from users where clue > 0")
+
+This does not return any Users (har har), but rather Struct's that will quack
+like Users. They'll be read-only as well.
+
+<tt>repository.adapter.query</tt> shouldn't be used if you aren't expecting a result set
+back.  If you want to just execute something against the database, use
+<tt>repository.adapter.execute</tt> instead.
+
+
+=== Can I get an query log of what DataMapper is issuing?
+
+Yup, to set this up, do:
+
+  DataMapper::Logger.new(STDOUT, 0)
+
+Incidentally, if you'd like to send a message into the DataMapper logger, do:
+
+  DataMapper.logger.debug { "something" }
+  DataMapper.logger.info { "something" }
+  DataMapper.logger.warn { "something" }
+  DataMapper.logger.error { "something" }
+  DataMapper.logger.fatal { "something" }

data/MIT-LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2007 Sam Smoot
+
+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/QUICKLINKS

@@ -0,0 +1,12 @@
+= Quick Links
+
+* Setup and Configuration - DataMapper
+* Finders and CRUD - 
+* Properties - DataMapper::Property
+* FAQ[link:/files/FAQ.html]
+* Contact Us
+  * Website - http://www.datamapper.org
+  * Bug Reports - http://wm.lighthouseapp.com/projects/4819-datamapper/overview
+  * IRC Channel - <tt>##datamapper</tt> on irc.freenode.net
+  * Mailing List - http://groups.google.com/group/datamapper/
+

data/README

@@ -0,0 +1,143 @@
+
+:include:QUICKLINKS
+
+= Why DataMapper?
+
+== Open Development
+
+DataMapper sports a very accessible code-base and a welcoming community.
+Outside contributions and feedback are welcome and encouraged, especially
+constructive criticism. Make your voice heard! Submit a
+ticket[http://wm.lighthouseapp.com/projects/4819-datamapper/overview] or
+patch[http://wm.lighthouseapp.com/projects/4819-datamapper/overview], speak up
+on our mailing-list[http://groups.google.com/group/datamapper/], chat with us
+on irc[irc://irc.freenode.net/#datamapper], write a spec, get it reviewed, ask
+for commit rights. It's as easy as that to become a contributor.
+
+== Identity Map
+
+One row in the data-store should equal one object reference. Pretty simple idea.
+Pretty profound impact. If you run the following code in ActiveRecord you'll
+see all <tt>false</tt> results. Do the same in DataMapper and it's
+<tt>true</tt> all the way down.
+
+  @parent = Tree.find(:first, :conditions => ['name = ?', 'bob'])
+
+  @parent.children.each do |child|
+    puts @parent.object_id == child.parent.object_id
+  end
+
+This makes DataMapper faster and allocate less resources to get things done.
+
+== Dirty Tracking
+
+When you save a model back to your data-store, DataMapper will only write
+the fields that actually changed. So it plays well with others. You can
+use it in an Integration data-store without worrying that your application will
+be a bad actor causing trouble for all of your other processes.
+
+You can also configure which strategy you'd like to use to track dirtiness.
+
+== Eager Loading
+
+Ready for something amazing? The following example executes only two queries.
+
+  zoos = Zoo.all
+  first = zoos.first
+  first.exhibits  # Loads the exhibits for all the Zoo objects in the zoos variable.
+
+Pretty impressive huh? The idea is that you aren't going to load a set of
+objects and use only an association in just one of them. This should hold up
+pretty well against a 99% rule. When you don't want it to work like this, just
+load the item you want in it's own set. So the DataMapper thinks ahead. We
+like to call it "performant by default". This feature single-handedly wipes
+out the "N+1 Query Problem". No need to specify an <tt>include</tt> option in
+your finders.
+
+== Laziness Can Be A Virtue
+
+Text fields are expensive in data-stores. They're generally stored in a
+different place than the rest of your data. So instead of a fast sequential
+read from your hard-drive, your data-store server has to hop around all over the
+place to get what it needs. Since ActiveRecord returns everything by default,
+adding a text field to a table slows everything down drastically, across the
+board.
+
+Not so with the DataMapper. Text fields are treated like in-row associations
+by default, meaning they only load when you need them. If you want more
+control you can enable or disable this feature for any field (not just
+text-fields) by passing a @lazy@ option to your field mapping with a value of
+<tt>true</tt> or <tt>false</tt>.
+
+  class Animal
+    include DataMapper::Resource
+    property :name, String
+    property :notes, Text, :lazy => false
+  end
+
+Plus, lazy-loading of text fields happens automatically and intelligently when
+working with associations.  The following only issues 2 queries to load up all
+of the notes fields on each animal:
+
+  animals = Animal.all
+  animals.each do |pet|
+    pet.notes
+  end
+
+== Plays Well With Others
+
+In ActiveRecord, all your fields are mapped, whether you want them or not.
+This slows things down. In the DataMapper you define your mappings in your
+model. So instead of an _ALTER TABLE ADD field_ in your data-store, you simply
+add a <tt>property :name, :string</tt> to your model. DRY. No schema.rb. No
+migration files to conflict or die without reverting changes. Your model
+drives the data-store, not the other way around.
+
+Unless of course you want to map to a legacy data-store. Raise your hand if you
+like seeing a method called <tt>col2Name</tt> on your model just because
+that's what it's called in an old data-store you can't afford to change right
+now? In DataMapper you control the mappings:
+
+  class Fruit
+    include DataMapper::Resource
+    storage_names[:repo] = 'frt'
+    property :name, String, :field => 'col2Name'
+  end
+
+== All Ruby, All The Time
+
+It's great that ActiveRecord allows you to write SQL when you need to, but
+should we have to so often?
+
+DataMapper supports issuing your own query, but it also provides more helpers
+and a unique hash-based condition syntax to cover more of the use-cases where
+issuing your own SQL would have been the only way to go. For example, any
+finder option that's non-standard is considered a condition. So you can write
+<tt>Zoo.all(:name => 'Dallas')</tt> and DataMapper will look for zoos with the
+name of 'Dallas'.
+
+It's just a little thing, but it's so much nicer than writing
+<tt>Zoo.find(:all, :conditions => ['name = ?', 'Dallas'])</tt>. What if you
+need other comparisons though? Try these:
+
+  Zoo.first(:name => 'Galveston')
+
+  # 'gt' means greater-than. We also do 'lt'.
+  Person.all(:age.gt => 30)
+
+  # 'gte' means greather-than-or-equal-to. We also do 'lte'.
+  Person.all(:age.gte => 30)
+
+  Person.all(:name.not => 'bob')
+
+  # If the value of a pair is an Array, we do an IN-clause for you.
+  Person.all(:name.like => 'S%', :id => [1, 2, 3, 4, 5])
+
+  # An alias for Zoo.find(11)
+  Zoo[11]
+
+  # Does a NOT IN () clause for you.
+  Person.all(:name.not => ['bob','rick','steve'])
+
+See? Fewer SQL fragments dirtying your Ruby code. And that's just a few of the
+nice syntax tweaks DataMapper delivers out of the box...

data/lib/dm-core.rb

@@ -0,0 +1,213 @@
+# This file begins the loading sequence.
+#
+# Quick Overview:
+# * Requires fastthread, support libs, and base.
+# * Sets the application root and environment for compatibility with frameworks
+#   such as Rails or Merb.
+# * Checks for the database.yml and loads it if it exists.
+# * Sets up the database using the config from the Yaml file or from the
+#   environment.
+#
+
+require 'date'
+require 'pathname'
+require 'set'
+require 'time'
+require 'yaml'
+
+require 'rubygems'
+
+gem 'addressable', '>=1.0.4'
+require 'addressable/uri'
+
+gem 'extlib', '=0.9.2'
+require 'extlib'
+
+begin
+  require 'fastthread'
+rescue LoadError
+  # fastthread not installed
+end
+
+dir = Pathname(__FILE__).dirname.expand_path / 'dm-core'
+
+require dir / 'support'
+require dir / 'resource'
+require dir / 'model'
+
+require dir / 'type'
+require dir / 'type_map'
+require dir / 'types'
+require dir / 'hook'
+require dir / 'associations'
+require dir / 'auto_migrations'
+require dir / 'identity_map'
+require dir / 'logger'
+require dir / 'migrator'
+require dir / 'naming_conventions'
+require dir / 'property_set'
+require dir / 'query'
+require dir / 'transaction'
+require dir / 'repository'
+require dir / 'scope'
+require dir / 'property'
+require dir / 'adapters'
+require dir / 'collection'
+require dir / 'is'
+
+# == Setup and Configuration
+# DataMapper uses URIs or a connection hash to connect to your data-store.
+# URI connections takes the form of:
+#   DataMapper.setup(:default, 'protocol://username:password@localhost:port/path/to/repo')
+#
+# Breaking this down, the first argument is the name you wish to give this
+# connection.  If you do not specify one, it will be assigned :default. If you
+# would like to connect to more than one data-store, simply issue this command
+# again, but with a different name specified.
+#
+# In order to issue ORM commands without specifying the repository context, you
+# must define the :default database. Otherwise, you'll need to wrap your ORM
+# calls in <tt>repository(:name) { }</tt>.
+#
+# Second, the URI breaks down into the access protocol, the username, the
+# server, the password, and whatever path information is needed to properly
+# address the data-store on the server.
+#
+# Here's some examples
+#   DataMapper.setup(:default, "sqlite3://path/to/your/project/db/development.db")
+#   DataMapper.setup(:default, "mysql://localhost/dm_core_test")
+#     # no auth-info
+#   DataMapper.setup(:default, "postgres://root:supahsekret@127.0.0.1/dm_core_test")
+#     # with auth-info
+#
+#
+# Alternatively, you can supply a hash as the second parameter, which would
+# take the form:
+#
+#   DataMapper.setup(:default, {
+#     :adapter  => 'adapter_name_here',
+#     :database => "path/to/repo",
+#     :username => 'username',
+#     :password => 'password',
+#     :host     => 'hostname'
+#   })
+#
+# === Logging
+# To turn on error logging to STDOUT, issue:
+#
+#   DataMapper::Logger.new(STDOUT, 0)
+#
+# You can pass a file location ("/path/to/log/file.log") in place of STDOUT.
+# see DataMapper::Logger for more information.
+#
+module DataMapper
+  extend Assertions
+
+  def self.root
+    @root ||= Pathname(__FILE__).dirname.parent.expand_path
+  end
+
+  ##
+  # Setups up a connection to a data-store
+  #
+  # @param Symbol name a name for the context, defaults to :default
+  # @param [Hash{Symbol => String}, Addressable::URI, String] uri_or_options
+  #   connection information
+  #
+  # @return Repository the resulting setup repository
+  #
+  # @raise ArgumentError "+name+ must be a Symbol, but was..." indicates that
+  #   an invalid argument was passed for name[Symbol]
+  # @raise [ArgumentError] "+uri_or_options+ must be a Hash, URI or String,
+  #   but was..." indicates that connection information could not be gleaned
+  #   from the given uri_or_options<Hash, Addressable::URI, String>
+  #
+  # -
+  # @api public
+  def self.setup(name, uri_or_options)
+    assert_kind_of 'name',           name,           Symbol
+    assert_kind_of 'uri_or_options', uri_or_options, Addressable::URI, Hash, String
+
+    case uri_or_options
+      when Hash
+        adapter_name = uri_or_options[:adapter].to_s
+      when String, Addressable::URI
+        uri_or_options = Addressable::URI.parse(uri_or_options) if uri_or_options.kind_of?(String)
+        adapter_name = uri_or_options.scheme
+    end
+
+    class_name = Extlib::Inflection.classify(adapter_name) + 'Adapter'
+
+    unless Adapters::const_defined?(class_name)
+      lib_name = "#{Extlib::Inflection.underscore(adapter_name)}_adapter"
+      begin
+        require root / 'lib' / 'dm-core' / 'adapters' / lib_name
+      rescue LoadError
+        require lib_name
+      end
+    end
+
+    Repository.adapters[name] = Adapters::const_get(class_name).new(name, uri_or_options)
+  end
+
+  ##
+  # Block Syntax
+  #   Pushes the named repository 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.
+  #
+  # @param [Symbol] args the name of a repository to act within or return, :default is default
+  # @yield [Proc] (optional) block to execute within the context of the named repository
+  # @demo spec/integration/repository_spec.rb
+  def self.repository(*args, &block) # :yields: current_context
+    if args.size > 1
+      raise ArgumentError, "Can only pass in one optional argument, but passed in #{args.size} arguments", caller
+    end
+
+    if args.any? && !args.first.kind_of?(Symbol)
+      raise ArgumentError, "First optional argument must be a Symbol, but was #{args.first.inspect}", caller
+    end
+
+    name = args.first
+
+    current_repository = if name
+      Repository.context.detect { |r| r.name == name } || Repository.new(name)
+    else
+      Repository.context.last || Repository.new(Repository.default_name)
+    end
+
+    return current_repository unless block_given?
+
+    current_repository.scope(&block)
+  end
+
+  # A logger should always be present. Lets be consistent with DO
+  Logger.new(nil, :off)
+
+  ##
+  # destructively migrates the repository upwards to match model definitions
+  #
+  # @param [Symbol] name repository to act on, :default is the default
+  def self.migrate!(name = Repository.default_name)
+    repository(name).migrate!
+  end
+
+  ##
+  # drops and recreates the repository upwards to match model definitions
+  #
+  # @param [Symbol] name repository to act on, :default is the default
+  def self.auto_migrate!(name = Repository.default_name)
+    repository(name).auto_migrate!
+  end
+
+  def self.auto_upgrade!(name = Repository.default_name)
+    repository(name).auto_upgrade!
+  end
+
+  def self.prepare(*args, &blk)
+    yield repository(*args)
+  end
+end