simply_stated 0.0.3 → 0.0.4

data/vendor/gems/ruby/1.8/gems/activerecord-2.3.5/README

@@ -0,0 +1,351 @@
+= Active Record -- Object-relation mapping put on rails
+
+Active Record connects business objects and database tables to create a persistable
+domain model where logic and data are presented in one wrapping. It's an implementation 
+of the object-relational mapping (ORM) pattern[http://www.martinfowler.com/eaaCatalog/activeRecord.html] 
+by the same name as described by Martin Fowler:
+
+  "An object that wraps a row in a database table or view, encapsulates 
+       the database access, and adds domain logic on that data."
+
+Active Record's main contribution to the pattern is to relieve the original of two stunting problems:
+lack of associations and inheritance. By adding a simple domain language-like set of macros to describe
+the former and integrating the Single Table Inheritance pattern for the latter, Active Record narrows the
+gap of functionality between the data mapper and active record approach.
+
+A short rundown of the major features:
+
+* Automated mapping between classes and tables, attributes and columns.
+
+   class Product < ActiveRecord::Base; end
+   
+   ...is automatically mapped to the table named "products", such as:
+   
+   CREATE TABLE products (
+     id int(11) NOT NULL auto_increment,
+     name varchar(255),
+     PRIMARY KEY  (id)
+   );
+
+   ...which again gives Product#name and Product#name=(new_name) 
+   
+  {Learn more}[link:classes/ActiveRecord/Base.html]
+
+
+* Associations between objects controlled by simple meta-programming macros. 
+
+   class Firm < ActiveRecord::Base
+     has_many   :clients
+     has_one    :account
+     belongs_to :conglomorate
+   end
+
+  {Learn more}[link:classes/ActiveRecord/Associations/ClassMethods.html]
+
+
+* Aggregations of value objects controlled by simple meta-programming macros. 
+
+   class Account < ActiveRecord::Base
+     composed_of :balance, :class_name => "Money",
+                 :mapping => %w(balance amount)
+     composed_of :address, 
+                 :mapping => [%w(address_street street), %w(address_city city)]
+   end
+
+  {Learn more}[link:classes/ActiveRecord/Aggregations/ClassMethods.html]
+
+
+* Validation rules that can differ for new or existing objects.
+
+    class Account < ActiveRecord::Base
+      validates_presence_of     :subdomain, :name, :email_address, :password
+      validates_uniqueness_of   :subdomain
+      validates_acceptance_of   :terms_of_service, :on => :create
+      validates_confirmation_of :password, :email_address, :on => :create
+    end
+
+  {Learn more}[link:classes/ActiveRecord/Validations.html]
+ 
+* Callbacks as methods or queues on the entire lifecycle (instantiation, saving, destroying, validating, etc).
+
+   class Person < ActiveRecord::Base
+     def before_destroy # is called just before Person#destroy
+       CreditCard.find(credit_card_id).destroy
+     end
+   end
+
+   class Account < ActiveRecord::Base
+     after_find :eager_load, 'self.class.announce(#{id})'
+   end
+
+  {Learn more}[link:classes/ActiveRecord/Callbacks.html]
+
+
+* Observers for the entire lifecycle
+
+   class CommentObserver < ActiveRecord::Observer
+     def after_create(comment) # is called just after Comment#save
+       Notifications.deliver_new_comment("david@loudthinking.com", comment)
+     end
+   end
+
+  {Learn more}[link:classes/ActiveRecord/Observer.html]
+
+
+* Inheritance hierarchies 
+
+   class Company < ActiveRecord::Base; end
+   class Firm < Company; end
+   class Client < Company; end
+   class PriorityClient < Client; end
+
+  {Learn more}[link:classes/ActiveRecord/Base.html]
+
+
+* Transactions
+
+    # Database transaction
+    Account.transaction do
+      david.withdrawal(100)
+      mary.deposit(100)
+    end
+
+  {Learn more}[link:classes/ActiveRecord/Transactions/ClassMethods.html]
+
+
+* Reflections on columns, associations, and aggregations
+
+    reflection = Firm.reflect_on_association(:clients)
+    reflection.klass # => Client (class)
+    Firm.columns # Returns an array of column descriptors for the firms table
+
+  {Learn more}[link:classes/ActiveRecord/Reflection/ClassMethods.html]
+
+
+* Direct manipulation (instead of service invocation)
+
+  So instead of (Hibernate[http://www.hibernate.org/] example):
+
+     long pkId = 1234;
+     DomesticCat pk = (DomesticCat) sess.load( Cat.class, new Long(pkId) );
+     // something interesting involving a cat...
+     sess.save(cat);
+     sess.flush(); // force the SQL INSERT
+
+  Active Record lets you:
+
+     pkId = 1234
+     cat = Cat.find(pkId)
+     # something even more interesting involving the same cat...
+     cat.save
+
+  {Learn more}[link:classes/ActiveRecord/Base.html]
+
+
+* Database abstraction through simple adapters (~100 lines) with a shared connector
+
+   ActiveRecord::Base.establish_connection(:adapter => "sqlite", :database => "dbfile")
+
+   ActiveRecord::Base.establish_connection(
+     :adapter  => "mysql", 
+     :host     => "localhost", 
+     :username => "me", 
+     :password => "secret", 
+     :database => "activerecord"
+   )
+
+  {Learn more}[link:classes/ActiveRecord/Base.html#M000081] and read about the built-in support for
+  MySQL[link:classes/ActiveRecord/ConnectionAdapters/MysqlAdapter.html], PostgreSQL[link:classes/ActiveRecord/ConnectionAdapters/PostgreSQLAdapter.html], SQLite[link:classes/ActiveRecord/ConnectionAdapters/SQLiteAdapter.html], Oracle[link:classes/ActiveRecord/ConnectionAdapters/OracleAdapter.html], SQLServer[link:classes/ActiveRecord/ConnectionAdapters/SQLServerAdapter.html], and DB2[link:classes/ActiveRecord/ConnectionAdapters/DB2Adapter.html].
+
+
+* Logging support for Log4r[http://log4r.sourceforge.net] and Logger[http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc]
+
+    ActiveRecord::Base.logger = Logger.new(STDOUT)
+    ActiveRecord::Base.logger = Log4r::Logger.new("Application Log")
+
+
+* Database agnostic schema management with Migrations
+
+    class AddSystemSettings < ActiveRecord::Migration
+      def self.up
+        create_table :system_settings do |t|
+          t.string :name
+          t.string :label
+          t.text :value
+          t.string :type
+          t.integer  :position
+        end
+
+        SystemSetting.create :name => "notice", :label => "Use notice?", :value => 1
+      end
+
+      def self.down
+        drop_table :system_settings
+      end
+    end
+
+  {Learn more}[link:classes/ActiveRecord/Migration.html]
+
+== Simple example (1/2): Defining tables and classes (using MySQL)
+
+Data definitions are specified only in the database. Active Record queries the database for 
+the column names (that then serves to determine which attributes are valid) on regular
+object instantiation through the new constructor and relies on the column names in the rows
+with the finders.
+ 
+   # CREATE TABLE companies (
+   #   id int(11) unsigned NOT NULL auto_increment,
+   #   client_of int(11),
+   #   name varchar(255),
+   #   type varchar(100),
+   #   PRIMARY KEY  (id)
+   # )
+
+Active Record automatically links the "Company" object to the "companies" table
+
+   class Company < ActiveRecord::Base
+     has_many :people, :class_name => "Person"
+   end
+
+   class Firm < Company
+     has_many :clients
+  
+     def people_with_all_clients
+      clients.inject([]) { |people, client| people + client.people }
+     end
+   end
+
+The foreign_key is only necessary because we didn't use "firm_id" in the data definition
+ 
+   class Client < Company
+     belongs_to :firm, :foreign_key => "client_of"
+   end
+
+   # CREATE TABLE people (
+   #   id int(11) unsigned NOT NULL auto_increment,
+   #   name text,
+   #   company_id text,
+   #   PRIMARY KEY  (id)
+   # )
+
+Active Record will also automatically link the "Person" object to the "people" table
+
+   class Person < ActiveRecord::Base
+     belongs_to :company
+   end
+
+== Simple example (2/2): Using the domain
+
+Picking a database connection for all the Active Records
+
+   ActiveRecord::Base.establish_connection(
+     :adapter  => "mysql", 
+     :host     => "localhost", 
+     :username => "me", 
+     :password => "secret", 
+     :database => "activerecord"
+   )
+
+Create some fixtures
+
+   firm = Firm.new("name" => "Next Angle")
+   # SQL: INSERT INTO companies (name, type) VALUES("Next Angle", "Firm")
+   firm.save
+
+   client = Client.new("name" => "37signals", "client_of" => firm.id)
+   # SQL: INSERT INTO companies (name, client_of, type) VALUES("37signals", 1, "Firm")
+   client.save
+
+Lots of different finders
+
+   # SQL: SELECT * FROM companies WHERE id = 1
+   next_angle = Company.find(1)
+
+   # SQL: SELECT * FROM companies WHERE id = 1 AND type = 'Firm'
+   next_angle = Firm.find(1)    
+
+   # SQL: SELECT * FROM companies WHERE id = 1 AND name = 'Next Angle'
+   next_angle = Company.find(:first, :conditions => "name = 'Next Angle'")
+
+   next_angle = Firm.find_by_sql("SELECT * FROM companies WHERE id = 1").first
+
+The supertype, Company, will return subtype instances
+
+   Firm === next_angle
+
+All the dynamic methods added by the has_many macro
+
+  next_angle.clients.empty?  # true
+  next_angle.clients.size    # total number of clients
+  all_clients = next_angle.clients
+
+Constrained finds makes access security easier when ID comes from a web-app
+
+   # SQL: SELECT * FROM companies WHERE client_of = 1 AND type = 'Client' AND id = 2
+   thirty_seven_signals = next_angle.clients.find(2)
+
+Bi-directional associations thanks to the "belongs_to" macro
+
+   thirty_seven_signals.firm.nil? # true
+
+
+== Philosophy 
+
+Active Record attempts to provide a coherent wrapper as a solution for the inconvenience that is 
+object-relational mapping. The prime directive for this mapping has been to minimize
+the amount of code needed to build a real-world domain model. This is made possible
+by relying on a number of conventions that make it easy for Active Record to infer
+complex relations and structures from a minimal amount of explicit direction.
+
+Convention over Configuration:
+* No XML-files!
+* Lots of reflection and run-time extension
+* Magic is not inherently a bad word 
+
+Admit the Database:
+* Lets you drop down to SQL for odd cases and performance
+* Doesn't attempt to duplicate or replace data definitions
+
+
+== Download
+
+The latest version of Active Record can be found at
+
+* http://rubyforge.org/project/showfiles.php?group_id=182
+
+Documentation can be found at 
+
+* http://ar.rubyonrails.com
+
+
+== Installation
+
+The prefered method of installing Active Record is through its GEM file. You'll need to have
+RubyGems[http://rubygems.rubyforge.org/wiki/wiki.pl] installed for that, though. If you have,
+then use:
+
+  % [sudo] gem install activerecord-1.10.0.gem
+
+You can also install Active Record the old-fashioned way with the following command:
+
+  % [sudo] ruby install.rb
+
+from its distribution directory.
+
+
+== License
+
+Active Record is released under the MIT license.
+
+
+== Support
+
+The Active Record homepage is http://www.rubyonrails.com. You can find the Active Record
+RubyForge page at http://rubyforge.org/projects/activerecord. And as Jim from Rake says:
+
+   Feel free to submit commits or feature requests.  If you send a patch,
+   remember to update the corresponding unit tests.  If fact, I prefer
+   new feature to be submitted in the form of new unit tests.
+
+For other information, feel free to ask on the rubyonrails-talk 
+(http://groups.google.com/group/rubyonrails-talk) mailing list.

data/vendor/gems/ruby/1.8/gems/activerecord-2.3.5/RUNNING_UNIT_TESTS

@@ -0,0 +1,36 @@
+== Creating the test database
+
+The default names for the test databases are "activerecord_unittest" and 
+"activerecord_unittest2". If you want to use another database name then be sure 
+to update the connection adapter setups you want to test with in 
+test/connections/<your database>/connection.rb. 
+When you have the database online, you can import the fixture tables with 
+the test/schema/*.sql files.
+
+Make sure that you create database objects with the same user that you specified in 
+connection.rb otherwise (on Postgres, at least) tests for default values will fail.
+
+== Running with Rake
+
+The easiest way to run the unit tests is through Rake. The default task runs
+the entire test suite for all the adapters. You can also run the suite on just
+one adapter by using the tasks test_mysql, test_sqlite, test_postgresql or any
+of the other test_ tasks. For more information, checkout the full array of rake
+tasks with "rake -T"
+
+Rake can be found at http://rake.rubyforge.org
+
+== Running by hand
+
+Unit tests are located in test/cases directory. If you only want to run a single test suite, 
+you can do so with:
+
+   rake test_mysql TEST=test/cases/base_test.rb
+   
+That'll run the base suite using the MySQL-Ruby adapter.  Some tests rely on the schema
+being initialized - you can initialize the schema with:
+
+  rake test_mysql TEST=test/cases/aaa_create_tables_test.rb
+
+
+

data/vendor/gems/ruby/1.8/gems/activerecord-2.3.5/Rakefile

@@ -0,0 +1,270 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+
+require File.join(File.dirname(__FILE__), 'lib', 'active_record', 'version')
+require File.expand_path(File.dirname(__FILE__)) + "/test/config"
+
+PKG_BUILD     = ENV['PKG_BUILD'] ? '.' + ENV['PKG_BUILD'] : ''
+PKG_NAME      = 'activerecord'
+PKG_VERSION   = ActiveRecord::VERSION::STRING + PKG_BUILD
+PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
+
+RELEASE_NAME  = "REL #{PKG_VERSION}"
+
+RUBY_FORGE_PROJECT = "activerecord"
+RUBY_FORGE_USER    = "webster132"
+
+MYSQL_DB_USER = 'rails'
+
+PKG_FILES = FileList[
+    "lib/**/*", "test/**/*", "examples/**/*", "doc/**/*", "[A-Z]*", "install.rb", "Rakefile"
+].exclude(/\bCVS\b|~$/)
+
+def run_without_aborting(*tasks)
+  errors = []
+
+  tasks.each do |task|
+    begin
+      Rake::Task[task].invoke
+    rescue Exception
+      errors << task
+    end
+  end
+
+  abort "Errors running #{errors.join(', ')}" if errors.any?
+end
+
+desc 'Run mysql, sqlite, and postgresql tests by default'
+task :default => :test
+
+desc 'Run mysql, sqlite, and postgresql tests'
+task :test do
+  tasks = defined?(JRUBY_VERSION) ?
+    %w(test_jdbcmysql test_jdbcsqlite3 test_jdbcpostgresql) :
+    %w(test_mysql test_sqlite3 test_postgresql)
+  run_without_aborting(*tasks)
+end
+
+for adapter in %w( mysql postgresql sqlite sqlite3 firebird db2 oracle sybase openbase frontbase jdbcmysql jdbcpostgresql jdbcsqlite3 jdbcderby jdbch2 jdbchsqldb )
+  Rake::TestTask.new("test_#{adapter}") { |t|
+    if adapter =~ /jdbc/
+      t.libs << "test" << "test/connections/jdbc_#{adapter}"
+    else
+      t.libs << "test" << "test/connections/native_#{adapter}"
+    end
+    adapter_short = adapter == 'db2' ? adapter : adapter[/^[a-z]+/]
+    t.test_files=Dir.glob( "test/cases/**/*_test{,_#{adapter_short}}.rb" ).sort
+    t.verbose = true
+  }
+
+  namespace adapter do
+    task :test => "test_#{adapter}"
+  end
+end
+
+namespace :mysql do
+  desc 'Build the MySQL test databases'
+  task :build_databases do
+    %x( echo "create DATABASE activerecord_unittest DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_unicode_ci " | mysql --user=#{MYSQL_DB_USER})
+    %x( echo "create DATABASE activerecord_unittest2 DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_unicode_ci " | mysql --user=#{MYSQL_DB_USER})
+  end
+
+  desc 'Drop the MySQL test databases'
+  task :drop_databases do
+    %x( mysqladmin --user=#{MYSQL_DB_USER} -f drop activerecord_unittest )
+    %x( mysqladmin --user=#{MYSQL_DB_USER} -f drop activerecord_unittest2 )
+  end
+
+  desc 'Rebuild the MySQL test databases'
+  task :rebuild_databases => [:drop_databases, :build_databases]
+end
+
+task :build_mysql_databases => 'mysql:build_databases'
+task :drop_mysql_databases => 'mysql:drop_databases'
+task :rebuild_mysql_databases => 'mysql:rebuild_databases'
+
+
+namespace :postgresql do
+  desc 'Build the PostgreSQL test databases'
+  task :build_databases do
+    %x( createdb -E UTF8 activerecord_unittest )
+    %x( createdb -E UTF8 activerecord_unittest2 )
+  end
+
+  desc 'Drop the PostgreSQL test databases'
+  task :drop_databases do
+    %x( dropdb activerecord_unittest )
+    %x( dropdb activerecord_unittest2 )
+  end
+
+  desc 'Rebuild the PostgreSQL test databases'
+  task :rebuild_databases => [:drop_databases, :build_databases]
+end
+
+task :build_postgresql_databases => 'postgresql:build_databases'
+task :drop_postgresql_databases => 'postgresql:drop_databases'
+task :rebuild_postgresql_databases => 'postgresql:rebuild_databases'
+
+
+namespace :frontbase do
+  desc 'Build the FrontBase test databases'
+  task :build_databases => :rebuild_frontbase_databases
+
+  desc 'Rebuild the FrontBase test databases'
+  task :rebuild_databases do
+    build_frontbase_database = Proc.new do |db_name, sql_definition_file|
+      %(
+        STOP DATABASE #{db_name};
+        DELETE DATABASE #{db_name};
+        CREATE DATABASE #{db_name};
+
+        CONNECT TO #{db_name} AS SESSION_NAME USER _SYSTEM;
+        SET COMMIT FALSE;
+
+        CREATE USER RAILS;
+        CREATE SCHEMA RAILS AUTHORIZATION RAILS;
+        COMMIT;
+
+        SET SESSION AUTHORIZATION RAILS;
+        SCRIPT '#{sql_definition_file}';
+
+        COMMIT;
+
+        DISCONNECT ALL;
+      )
+    end
+    create_activerecord_unittest  = build_frontbase_database['activerecord_unittest',  File.join(SCHEMA_ROOT, 'frontbase.sql')]
+    create_activerecord_unittest2 = build_frontbase_database['activerecord_unittest2', File.join(SCHEMA_ROOT, 'frontbase2.sql')]
+    execute_frontbase_sql = Proc.new do |sql|
+      system(<<-SHELL)
+      /Library/FrontBase/bin/sql92 <<-SQL
+      #{sql}
+      SQL
+      SHELL
+    end
+    execute_frontbase_sql[create_activerecord_unittest]
+    execute_frontbase_sql[create_activerecord_unittest2]
+  end
+end
+
+task :build_frontbase_databases => 'frontbase:build_databases'
+task :rebuild_frontbase_databases => 'frontbase:rebuild_databases'
+
+
+# Generate the RDoc documentation
+
+Rake::RDocTask.new { |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = "Active Record -- Object-relation mapping put on rails"
+  rdoc.options << '--line-numbers' << '--inline-source' << '-A cattr_accessor=object'
+  rdoc.options << '--charset' << 'utf-8'
+  rdoc.template = ENV['template'] ? "#{ENV['template']}.rb" : '../doc/template/horo'
+  rdoc.rdoc_files.include('README', 'RUNNING_UNIT_TESTS', 'CHANGELOG')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.exclude('lib/active_record/vendor/*')
+  rdoc.rdoc_files.include('dev-utils/*.rb')
+}
+
+# Enhance rdoc task to copy referenced images also
+task :rdoc do
+  FileUtils.mkdir_p "doc/files/examples/"
+  FileUtils.copy "examples/associations.png", "doc/files/examples/associations.png"
+end
+
+
+# Create compressed packages
+
+dist_dirs = [ "lib", "test", "examples" ]
+
+spec = Gem::Specification.new do |s|
+  s.platform = Gem::Platform::RUBY
+  s.name = PKG_NAME
+  s.version = PKG_VERSION
+  s.summary = "Implements the ActiveRecord pattern for ORM."
+  s.description = %q{Implements the ActiveRecord pattern (Fowler, PoEAA) for ORM. It ties database tables and classes together for business objects, like Customer or Subscription, that can find, save, and destroy themselves without resorting to manual SQL.}
+
+  s.files = [ "Rakefile", "install.rb", "README", "RUNNING_UNIT_TESTS", "CHANGELOG" ]
+  dist_dirs.each do |dir|
+    s.files = s.files + Dir.glob( "#{dir}/**/*" ).delete_if { |item| item.include?( "\.svn" ) }
+  end
+
+  s.add_dependency('activesupport', '= 2.3.5' + PKG_BUILD)
+
+  s.files.delete FIXTURES_ROOT + "/fixture_database.sqlite"
+  s.files.delete FIXTURES_ROOT + "/fixture_database_2.sqlite"
+  s.files.delete FIXTURES_ROOT + "/fixture_database.sqlite3"
+  s.files.delete FIXTURES_ROOT + "/fixture_database_2.sqlite3"
+  s.require_path = 'lib'
+  s.autorequire = 'active_record'
+
+  s.has_rdoc = true
+  s.extra_rdoc_files = %w( README )
+  s.rdoc_options.concat ['--main',  'README']
+
+  s.author = "David Heinemeier Hansson"
+  s.email = "david@loudthinking.com"
+  s.homepage = "http://www.rubyonrails.org"
+  s.rubyforge_project = "activerecord"
+end
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+task :lines do
+  lines, codelines, total_lines, total_codelines = 0, 0, 0, 0
+
+  for file_name in FileList["lib/active_record/**/*.rb"]
+    next if file_name =~ /vendor/
+    f = File.open(file_name)
+
+    while line = f.gets
+      lines += 1
+      next if line =~ /^\s*$/
+      next if line =~ /^\s*#/
+      codelines += 1
+    end
+    puts "L: #{sprintf("%4d", lines)}, LOC #{sprintf("%4d", codelines)} | #{file_name}"
+
+    total_lines     += lines
+    total_codelines += codelines
+
+    lines, codelines = 0, 0
+  end
+
+  puts "Total: Lines #{total_lines}, LOC #{total_codelines}"
+end
+
+
+# Publishing ------------------------------------------------------
+
+desc "Publish the beta gem"
+task :pgem => [:package] do
+  require 'rake/contrib/sshpublisher'
+  Rake::SshFilePublisher.new("gems.rubyonrails.org", "/u/sites/gems/gems", "pkg", "#{PKG_FILE_NAME}.gem").upload
+  `ssh gems.rubyonrails.org '/u/sites/gems/gemupdate.sh'`
+end
+
+desc "Publish the API documentation"
+task :pdoc => [:rdoc] do
+  require 'rake/contrib/sshpublisher'
+  Rake::SshDirPublisher.new("wrath.rubyonrails.org", "public_html/ar", "doc").upload
+end
+
+desc "Publish the release files to RubyForge."
+task :release => [ :package ] do
+  require 'rubyforge'
+  require 'rake/contrib/rubyforgepublisher'
+
+  packages = %w( gem tgz zip ).collect{ |ext| "pkg/#{PKG_NAME}-#{PKG_VERSION}.#{ext}" }
+
+  rubyforge = RubyForge.new
+  rubyforge.login
+  rubyforge.add_release(PKG_NAME, PKG_NAME, "REL #{PKG_VERSION}", *packages)
+end