sam-dm-core 0.9.6

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.txt

@@ -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/Rakefile

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+require 'pathname'
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+require 'lib/dm-core/version'
+
+ROOT = Pathname(__FILE__).dirname.expand_path
+
+AUTHOR = "Sam Smoot"
+EMAIL  = "ssmoot@gmail.com"
+GEM_NAME = "dm-core"
+GEM_VERSION = DataMapper::VERSION
+GEM_DEPENDENCIES = ["data_objects", ">=0.9.5"], ["extlib", ">=0.9.5"],
+                   ["rspec", ">=1.1.3"], ["addressable", ">=1.0.4"]
+
+
+PROJECT_NAME = "datamapper"
+PROJECT_DESCRIPTION = "Faster, Better, Simpler."
+PROJECT_SUMMARY = "An Object/Relational Mapper for Ruby"
+PROJECT_URL  = "http://datamapper.org"
+
+require ROOT + 'tasks/hoe'
+require ROOT + 'tasks/gemspec'
+require ROOT + 'tasks/install'
+require ROOT + 'tasks/dm'
+require ROOT + 'tasks/doc'
+require ROOT + 'tasks/ci'

data/SPECS

@@ -0,0 +1,63 @@
+Reading Specs
+=============
+
+  Blah blah blah...
+  
+Writing Specs
+=============
+
+  Here are some general dos and don'ts
+  
+  = DO:
+  
+  * Write more specs for error conditions than clean conditions.
+  * Write specs with readability in mind. Somebody knew to DataMapper should be
+    able to read specs to learn how something works.
+  * Use existing models that are part of a metaphor.
+  * Nest describe blocks (2 or 3 levels deep is probably fine).
+  * Limit a describe block to 10 - 15 examples.
+  * Group specs by method being tested. (See the 'Ordering Specs' section)
+  * Use custom matchers.
+  
+  = DON'T:
+  
+  * Spec more than one unit of functionality in an example. An example should be
+    as short as possible (while still remaining readable).
+  * Spec implementation. Refactoring code should not break specs.
+  * Declare models in the spec file.
+  
+  And a final do: Do go against the guidelines if your best judgement tells you
+  to. These are just guidelines and are obviously not fast rules.
+
+Models
+======
+
+  Models are declared in separate files as opposed to individual spec files for
+  two reasons. The first is to improve readability. By creating as few models
+  as possible and sharing these models throughout the specs, a reader can
+  become familiar with the models being used quicker. Models also follow a
+  few simple metaphors, such as a zoo, a blog implementation, etc... Following
+  metaphors makes it easier for a reader to guess what is going on with respect
+  to the models.
+  
+  The second reason is to allow the spec environment to be as pristine as
+  possible going into an example. Models being loaded from the model directory
+  are tracked and reloaded before each example. Any changes that might be made
+  to the model are reset at the end.
+
+Mocks and Stubs
+===============
+
+  Obviously, mocks and stubs are a powerful feature when it comes to BDD;
+  however, remember that you are writing specs for behavior and NOT
+  implementation.
+  
+Ordering Specs
+==============
+
+  Specs aren't much use if nobody can find where anything is, so keeping specs
+  well organized is critical. Currently, we are trying out the following
+  structure:
+  
+    * List guidelines here...
+  

data/TODO

@@ -0,0 +1 @@
+See: http://github.com/sam/dm-core/wikis

data/lib/dm-core.rb

@@ -0,0 +1,224 @@
+# 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.5'
+require 'extlib'
+require "extlib/inflection"
+
+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 / 'dependency_queue'
+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 => e
+        begin
+          require lib_name
+        rescue Exception
+          # library not found, raise the original error
+          raise e
+        end
+      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!(repository_name = nil)
+    AutoMigrator.auto_migrate(repository_name)
+  end
+
+  def self.auto_upgrade!(repository_name = nil)
+    AutoMigrator.auto_upgrade(repository_name)
+  end
+
+  def self.prepare(*args, &blk)
+    yield repository(*args)
+  end
+
+  def self.dependency_queue
+    @dependency_queue ||= DependencyQueue.new
+  end
+end