sequel 1.3 → 1.4.0

data/CHANGELOG

@@ -0,0 +1,127 @@
+=== 1.4.0 (2008-04-08)
+
+* Don't mark a column as changed unless the new value is different from the current value (tamas.denes, jeremyevans) (#203).
+
+* Switch gem name from "sequel_model" to just "sequel", which required large version bump (jeremyevans).
+
+* Add :select option to many_to_many associations, default to selecting only the associated model table and not the join table (jeremyevans) (#208).
+
+* Add :reciprocal one_to_many association option, for setting corresponding many_to_one instance variable (jeremyevans).
+
+* Add eager loading implementation (jeremyevans).
+
+* Change *_to_many associations so that the all associations are considered :cache=>true (jeremyevans).
+
+* Fix associations with block arguments and :cache=>true (jeremyevans).
+
+=== 0.5.0.2 (2008-03-12)
+
+* More fixes for Model.associate to accept strings and symbols as class references.
+
+=== 0.5.0.1 (2008-03-09)
+
+* Fixed Model.associate to accept class and class name in :class option.
+
+=== 0.5 (2008-03-08)
+
+* Merged new associations branch into trunk.
+
+* Rewrote RDoc for associations.
+
+* Added has_and_belongs_to_many alias for many_to_many.
+
+* Added support for optional dataset block.
+
+* Added :order option to order association datasets.
+
+* Added :cache option to return and cache array of objects for association.
+
+* Changed one_to_many, many_to_many associations to return dataset by default.
+
+* Added has_many, belongs_to aliases.
+
+* Refactored associations code.
+
+* Added deprecations for old-style relations.
+
+* Completed specs for new associations code.
+
+* New associations code by Jeremy Evans (replaces relations code.)
+
+=== 0.4.2 (2008-02-29)
+
+* Fixed one_to_many implicit key to work correctly for namespaced classes (#167).
+
+* Fixed Model.db= to affect the underlying dataset (#183).
+
+* Fixed Model.implicit_table_name to disregard namespaces.
+
+=== 0.4.1 (2008-02-10)
+
+* Implemented Model#inspect (#151).
+
+* Changed Model#method_missing to short-circuit and bypass checking #columns if the values hash already contains the relevant column (#150).
+
+* Updated to reflect changes in sequel_core (Dataset#clone_merge renamed to Dataset#clone).
+
+=== 0.4 (2008-02-05)
+
+* Fixed Model#set to work with string keys (#143).
+
+* Fixed Model.create to correctly initialize instances marked as new (#135).
+
+* Fixed Model#initialize to convert string keys into symbol keys. This also fixes problem with validating objects initialized with string keys (#136).
+
+=== 0.3.3 (2008-01-25)
+
+* Finalized support for virtual attributes.
+
+=== 0.3.2.1 (2008-01-24)
+
+* Fixed Model.dataset to correctly set the dataset if using implicit naming or inheriting the superclass dataset (thanks celldee).
+
+=== 0.3.2 (2008-01-24)
+
+* Added Model#update_with_params method with support for virtual attributes and auto-filtering of unrelated parameters, and changed Model.create_with_params to support virtual attributes (#128).
+
+* Cleaned up gem spec (#132).
+
+* Removed validations code. Now relying on validations in assistance gem.
+
+=== 0.3.1 (2008-01-21)
+
+* Changed Model.dataset to use inflector to pluralize the class name into the table name. Works in similar fashion to table names in AR or DM.
+
+=== 0.3 (2008-01-18)
+
+* Implemented Validatable::Errors class.
+
+* Added Model#reload as alias to Model#refresh.
+
+* Changed Model.create to accept a block (#126).
+
+* Rewrote validations.
+
+* Fixed Model#initialize to accept nil values (#115).
+
+=== 0.2 (2008-01-02)
+
+* Removed deprecated Model.recreate_table method.
+
+* Removed deprecated :class and :on options from one_to_many macro.
+
+* Removed deprecated :class option from one_to_one macro.
+
+* Removed deprecated Model#pkey method.
+
+* Changed dependency to sequel_core.
+
+* Removed examples from sequel core.
+
+* Additional specs. We're now at 100% coverage.
+
+* Refactored hooks code. Hooks are now inheritable, and can be defined by supplying a block or a method name, or by overriding the hook instance method. Hook chains can now be broken by returning false (#111, #112).
+
+=== 0.1 (2007-12-30)
+
+* Moved model code from sequel into separate model sub-project.

data/COPYING

@@ -1,4 +1,5 @@
 Copyright (c) 2007-2008 Sharon Rosner
+Copyright (c) 2008 Jeremy Evans
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to

data/README

@@ -7,18 +7,19 @@ Sequel makes it easy to deal with multiple records without having to break your
 == Resources
 
 * {Project page}[http://code.google.com/p/ruby-sequel/]
-* {Source code}[http://ruby-sequel.googlecode.com/svn/]
+* {Source code}[http://github.com/jeremyevans/sequel]
 * {Bug tracking}[http://code.google.com/p/ruby-sequel/issues/list]
 * {Google group}[http://groups.google.com/group/sequel-talk]
 * {RubyForge page}[http://rubyforge.org/projects/sequel/]
+* {API RDoc}[http://sequel.rubyforge.org]
 
 To check out the source code:
   
-  svn co http://ruby-sequel.googlecode.com/svn/trunk
+  git clone git://github.com/jeremyevans/sequel.git
   
 === Contact
 
-If you have any comments or suggestions please send an email to ciconia at gmail.com and I'll get back to you.
+If you have any comments or suggestions please post to the Google group.
 
 == Installation
 
@@ -208,7 +209,7 @@ Or calculate a sum:
   
 You can also specify descending order
 
-  posts.order(:stamp.DESC)
+  posts.order(:stamp.desc)
 
 === Deleting Records
 

data/Rakefile

@@ -9,17 +9,30 @@ include FileUtils
 # Configuration
 ##############################################################################
 NAME = "sequel"
-VERS = "1.3"
+VERS = "1.4.0"
 CLEAN.include ["**/.*.sw?", "pkg/*", ".config", "doc/*", "coverage/*"]
 RDOC_OPTS = [
   "--quiet", 
-  "--title", "Sequel: Database access for Ruby",
+  "--title", "Sequel: The Database Toolkit for Ruby",
   "--opname", "index.html",
   "--line-numbers", 
   "--main", "README",
   "--inline-source"
 ]
 
+##############################################################################
+# RDoc
+##############################################################################
+task :doc => [:rdoc]
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = "doc/rdoc"
+  rdoc.options += RDOC_OPTS
+  rdoc.main = "README"
+  rdoc.title = "Sequel: The Database Toolkit for Ruby"
+  rdoc.rdoc_files.add ["README", "COPYING", "lib/sequel_model.rb", "lib/**/*.rb"]
+end
+
 ##############################################################################
 # Gem packaging
 ##############################################################################
@@ -27,34 +40,34 @@ desc "Packages up Sequel."
 task :default => [:package]
 task :package => [:clean]
 
-RDOC_OPTS = [
-  "--quiet", 
-  "--title", "Sequel Model: The Database Toolkit for Ruby",
-  "--opname", "index.html",
-  "--line-numbers", 
-  "--main", "README",
-  "--inline-source"
-]
-
 spec = Gem::Specification.new do |s|
   s.name = NAME
   s.rubyforge_project = 'sequel'
   s.version = VERS
   s.platform = Gem::Platform::RUBY
-  s.summary = "Database access for Ruby"
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README", "CHANGELOG", "COPYING"]
+  s.rdoc_options += RDOC_OPTS + 
+    ["--exclude", "^(examples|extras)\/", "--exclude", "lib/sequel_model.rb"]
+  s.summary = "The Database Toolkit for Ruby: Model Classes"
   s.description = s.summary
-  s.author = "Sharon Rosner"
-  s.email = "ciconia@gmail.com"
+  s.author = "Jeremy Evans"
+  s.email = "code@jeremyevans.net"
   s.homepage = "http://sequel.rubyforge.org"
   s.required_ruby_version = ">= 1.8.4"
 
-  s.has_rdoc = true
-  s.extra_rdoc_files = ["README", "COPYING"]
+  case RUBY_PLATFORM
+  when /java/
+    s.platform = "jruby"
+  else
+    s.platform = Gem::Platform::RUBY
+  end
 
-  s.add_dependency("sequel_core")
-  s.add_dependency("sequel_model")
+  s.add_dependency("assistance", '>= 0.1.2')
+  s.add_dependency("sequel_core", '= 1.4.0')
   
-  s.files = %w(Rakefile) + Dir.glob("{lib}/**/*")
+  s.files = %w(COPYING README Rakefile) + Dir.glob("{doc,spec,lib}/**/*")
+
   s.require_path = "lib"
 end
 
@@ -80,16 +93,56 @@ task :uninstall => [:clean] do
   sh %{sudo gem uninstall #{NAME}}
 end
 
-task :tag do
-  cwd = FileUtils.pwd
-  sh %{cd ../.. && svn copy #{cwd} tags/#{NAME}-#{VERS} && svn commit -m "#{NAME}-#{VERS} tag." tags}
-end
-
 ##############################################################################
-# gem release
+# gem and rdoc release
 ##############################################################################
 task :release => [:package] do
   sh %{rubyforge login}
   sh %{rubyforge add_release sequel #{NAME} #{VERS} pkg/#{NAME}-#{VERS}.tgz}
   sh %{rubyforge add_file sequel #{NAME} #{VERS} pkg/#{NAME}-#{VERS}.gem}
 end
+
+##############################################################################
+# specs
+##############################################################################
+require "spec/rake/spectask"
+sqcdir = File.join(File.dirname(File.dirname(__FILE__)), 'sequel_core', 'lib') 
+fixRUBYLIB = Proc.new{ENV['RUBYLIB'] ? (ENV['RUBYLIB'] += ":#{sqcdir}") : (ENV['RUBYLIB'] = sqcdir)}
+
+desc "Run specs with coverage"
+Spec::Rake::SpecTask.new("spec") do |t|
+  fixRUBYLIB.call
+  t.spec_files = FileList["spec/**/*_spec.rb"]
+  t.spec_opts  = File.read("spec/spec.opts").split("\n")
+  t.rcov_opts  = File.read("spec/rcov.opts").split("\n")
+  t.rcov = true
+end
+
+desc "Run specs without coverage"
+Spec::Rake::SpecTask.new("spec_no_cov") do |t|
+  fixRUBYLIB.call
+  t.spec_files = FileList["spec/**/*_spec.rb"]
+  t.spec_opts  = File.read("spec/spec.opts").split("\n")
+end
+
+desc "check documentation coverage"
+task :dcov do
+  sh "find lib -name '*.rb' | xargs dcov"
+end
+
+##############################################################################
+# Statistics
+##############################################################################
+
+STATS_DIRECTORIES = [
+  %w(Code   lib/),
+  %w(Spec   spec/)
+].collect { |name, dir| [ name, "./#{dir}" ] }.select { |name, dir| File.directory?(dir) }
+
+desc "Report code statistics (KLOCs, etc) from the application"
+task :stats do
+  require "extra/stats"
+  verbose = true
+  CodeStatistics.new(*STATS_DIRECTORIES).to_s
+end
+

data/lib/sequel.rb

@@ -1,2 +1 @@
-require 'sequel_core'
-require 'sequel_model'
+require 'sequel_model'

data/lib/sequel_model.rb

@@ -0,0 +1,324 @@
+require 'sequel_core'
+
+module Sequel
+  class Model
+    alias_method :model, :class
+  end
+end
+
+files = %w[
+  base hooks record schema associations 
+  caching plugins validations eager_loading
+]
+dir = File.join(File.dirname(__FILE__), "sequel_model")
+files.each {|f| require(File.join(dir, f))}
+
+module Sequel
+  # == Sequel Models
+  # 
+  # Models in Sequel are based on the Active Record pattern described by Martin Fowler (http://www.martinfowler.com/eaaCatalog/activeRecord.html). A model class corresponds to a table or a dataset, and an instance of that class wraps a single record in the model's underlying dataset.
+  # 
+  # Model classes are defined as regular Ruby classes:
+  # 
+  #   DB = Sequel('sqlite:/blog.db')
+  #   class Post < Sequel::Model
+  #     set_dataset DB[:posts]
+  #   end
+  # 
+  # You can also use the shorthand form:
+  # 
+  #   DB = Sequel('sqlite:/blog.db')
+  #   class Post < Sequel::Model
+  #   end
+  # 
+  # === Model instances
+  # 
+  # Model instance are identified by a primary key. By default, Sequel assumes the primary key column to be :id. The Model#[] method can be used to fetch records by their primary key:
+  # 
+  #   post = Post[123]
+  # 
+  # The Model#pk method is used to retrieve the record's primary key value:
+  # 
+  #   post.pk #=> 123
+  # 
+  # Sequel models allow you to use any column as a primary key, and even composite keys made from multiple columns:
+  # 
+  #   class Post < Sequel::Model
+  #     set_primary_key [:category, :title]
+  #   end
+  # 
+  #   post = Post['ruby', 'hello world']
+  #   post.pk #=> ['ruby', 'hello world']
+  # 
+  # You can also define a model class that does not have a primary key, but then you lose the ability to update records.
+  # 
+  # A model instance can also be fetched by specifying a condition:
+  # 
+  #   post = Post[:title => 'hello world']
+  #   post = Post.find {:stamp < 10.days.ago}
+  # 
+  # === Iterating over records
+  # 
+  # A model class lets you iterate over specific records by acting as a proxy to the underlying dataset. This means that you can use the entire Dataset API to create customized queries that return model instances, e.g.:
+  # 
+  #   Post.filter(:category => 'ruby').each {|post| p post}
+  # 
+  # You can also manipulate the records in the dataset:
+  # 
+  #   Post.filter {:stamp < 7.days.ago}.delete
+  #   Post.filter {:title =~ /ruby/}.update(:category => 'ruby')
+  # 
+  # === Accessing record values
+  # 
+  # A model instances stores its values as a hash:
+  # 
+  #   post.values #=> {:id => 123, :category => 'ruby', :title => 'hello world'}
+  # 
+  # You can read the record values as object attributes:
+  # 
+  #   post.id #=> 123
+  #   post.title #=> 'hello world'
+  # 
+  # You can also change record values:
+  # 
+  #   post.title = 'hey there'
+  #   post.save
+  # 
+  # Another way to change values by using the #set method:
+  # 
+  #   post.set(:title => 'hey there')
+  # 
+  # === Creating new records
+  # 
+  # New records can be created by calling Model.create:
+  # 
+  #   post = Post.create(:title => 'hello world')
+  # 
+  # Another way is to construct a new instance and save it:
+  # 
+  #   post = Post.new
+  #   post.title = 'hello world'
+  #   post.save
+  # 
+  # You can also supply a block to Model.new and Model.create:
+  # 
+  #   post = Post.create {|p| p.title = 'hello world'}
+  # 
+  #   post = Post.new do |p|
+  #     p.title = 'hello world'
+  #     p.save
+  #   end
+  # 
+  # === Hooks
+  # 
+  # You can execute custom code when creating, updating, or deleting records by using hooks. The before_create and after_create hooks wrap record creation. The before_update and after_update wrap record updating. The before_save and after_save wrap record creation and updating. The before_destroy and after_destroy wrap destruction.
+  # 
+  # Hooks are defined by supplying a block:
+  # 
+  #   class Post < Sequel::Model
+  #     after_create do
+  #       set(:created_at => Time.now)
+  #     end
+  # 
+  #     after_destroy do
+  #       author.update_post_count
+  #     end
+  #   end
+  # 
+  # === Deleting records
+  # 
+  # You can delete individual records by calling #delete or #destroy. The only difference between the two methods is that #destroy invokes before_destroy and after_destroy hooks, while #delete does not:
+  # 
+  #   post.delete #=> bypasses hooks
+  #   post.destroy #=> runs hooks
+  # 
+  # Records can also be deleted en-masse by invoking Model.delete and Model.destroy. As stated above, you can specify filters for the deleted records:
+  # 
+  #   Post.filter(:category => 32).delete #=> bypasses hooks
+  #   Post.filter(:category => 32).destroy #=> runs hooks
+  # 
+  # Please note that if Model.destroy is called, each record is deleted 
+  # separately, but Model.delete deletes all relevant records with a single 
+  # SQL statement.
+  # 
+  # === Associations
+  # 
+  # Sequel provides macros for the three most common types of associations: 
+  # many_to_one, one_to_many and many_to_many (equivalent to ActiveRecord's
+  # belongs_to, has_many and has_and_belongs_to_many).
+  # 
+  # Associations are defined in similar fashion to ActiveRecord:
+  #
+  #   class Post < Sequel::Model
+  #     belongs_to :author
+  #   end
+  #
+  #   class Author < Sequel::Model
+  #     has_many :posts
+  #   end
+  # 
+  # Another way to define an association in a Sequel model is as a regular
+  # instance method:
+  # 
+  #   class Post < Sequel::Model
+  #     def author; Author[author_id]; end
+  #   end
+  # 
+  #   class Author < Sequel::Model
+  #     def posts; Post.filter(:author_id => pk); end
+  #   end
+  # 
+  # === Caching model instances with memcached
+  # 
+  # Sequel models can be cached using memcached based on their primary keys. The use of memcached can significantly reduce database load by keeping model instances in memory. The set_cache method is used to specify caching:
+  # 
+  #   require 'memcache'
+  #   CACHE = MemCache.new 'localhost:11211', :namespace => 'blog'
+  # 
+  #   class Author < Sequel::Model
+  #     set_cache CACHE, :ttl => 3600
+  #   end
+  # 
+  #   Author[333] # database hit
+  #   Author[333] # cache hit
+  # 
+  # === Extending the underlying dataset
+  # 
+  # The obvious way to add table-wide logic is to define class methods to the model class definition. That way you can define subsets of the underlying dataset, change the ordering, or perform actions on multiple records:
+  # 
+  #   class Post < Sequel::Model
+  #     def self.old_posts
+  #       filter {:stamp < 30.days.ago}
+  #     end
+  # 
+  #     def self.clean_old_posts
+  #       old_posts.delete
+  #     end
+  #   end
+  # 
+  # You can also implement table-wide logic by defining methods on the dataset:
+  # 
+  #   class Post < Sequel::Model
+  #     def dataset.old_posts
+  #       filter {:stamp < 30.days.ago}
+  #     end
+  # 
+  #     def dataset.clean_old_posts
+  #       old_posts.delete
+  #     end
+  #   end
+  # 
+  # This is the recommended way of implementing table-wide operations, and allows you to have access to your model API from filtered datasets as well:
+  # 
+  #   Post.filter(:category => 'ruby').clean_old_posts
+  # 
+  # Sequel models also provide a short hand notation for filters:
+  # 
+  #   class Post < Sequel::Model
+  #     subset(:old_posts) {:stamp < 30.days.ago}
+  #     subset :invisible, :visible => false
+  #   end
+  # 
+  # === Defining the underlying schema
+  # 
+  # Model classes can also be used as a place to define your table schema and control it. The schema DSL is exactly the same provided by Sequel::Schema::Generator:
+  # 
+  #   class Post < Sequel::Model
+  #     set_schema do
+  #       primary_key :id
+  #       text :title
+  #       text :category
+  #       foreign_key :author_id, :table => :authors
+  #     end
+  #   end
+  # 
+  # You can then create the underlying table, drop it, or recreate it:
+  # 
+  #   Post.table_exists?
+  #   Post.create_table
+  #   Post.drop_table
+  #   Post.create_table! # drops the table if it exists and then recreates it
+  # 
+  class Model
+    extend Associations
+    # Returns a string representation of the model instance including
+    # the class name and values.
+    def inspect
+      "#<%s @values=%s>" % [self.class.name, @values.inspect]
+    end
+    
+    # Defines a method that returns a filtered dataset.
+    def self.subset(name, *args, &block)
+      dataset.meta_def(name) {filter(*args, &block)}
+    end
+    
+    # Finds a single record according to the supplied filter, e.g.:
+    #
+    #   Ticket.find :author => 'Sharon' # => record
+    #   Ticket.find {:price == 17} # => Dataset
+    #
+    def self.find(*args, &block)
+      dataset.filter(*args, &block).first
+    end
+    
+    # TODO: doc
+    def self.[](*args)
+      args = args.first if (args.size == 1)
+      if args === true || args === false
+        raise Error::InvalidFilter, "Did you mean to supply a hash?"
+      end
+      dataset[(Hash === args) ? args : primary_key_hash(args)]
+    end
+    
+    # TODO: doc
+    def self.fetch(*args)
+      db.fetch(*args).set_model(self)
+    end
+
+    # Like find but invokes create with given conditions when record does not
+    # exists.
+    def self.find_or_create(cond)
+      find(cond) || create(cond)
+    end
+
+    ############################################################################
+
+    # Deletes all records in the model's table.
+    def self.delete_all
+      dataset.delete
+    end
+
+    # Like delete_all, but invokes before_destroy and after_destroy hooks if used.
+    def self.destroy_all
+      dataset.destroy
+    end
+        
+    def self.is_dataset_magic_method?(m)
+      method_name = m.to_s
+      Sequel::Dataset::MAGIC_METHODS.each_key do |r|
+        return true if method_name =~ r
+      end
+      false
+    end
+    
+    def self.method_missing(m, *args, &block) #:nodoc:
+      Thread.exclusive do
+        if dataset.respond_to?(m) || is_dataset_magic_method?(m)
+          instance_eval("def #{m}(*args, &block); dataset.#{m}(*args, &block); end")
+        end
+      end
+      respond_to?(m) ? send(m, *args, &block) : super(m, *args)
+    end
+
+    # TODO: Comprehensive description goes here!
+    def self.join(*args)
+      table_name = dataset.opts[:from].first
+      dataset.join(*args).select(table_name.to_sym.ALL)
+    end
+    
+    # Returns an array containing all of the models records.
+    def self.all
+      dataset.all
+    end
+  end
+end