module Sequel
class Model
extend Enumerable
extend Inflections
extend Metaprogramming
include Metaprogramming
# Class methods for Sequel::Model that implement basic model functionality.
#
# * All of the method names in Model::DATASET_METHODS have class methods created that call
# the Model's dataset with the method of the same name with the given arguments.
module ClassMethods
# Which columns should be the only columns allowed in a call to a mass assignment method (e.g. set)
# (default: not set, so all columns not otherwise restricted).
attr_reader :allowed_columns
# Array of modules that extend this model's dataset. Stored
# so that if the model's dataset is changed, it will be extended
# with all of these modules.
attr_reader :dataset_method_modules
# Hash of dataset methods with method name keys and proc values that are
# stored so when the dataset changes, methods defined with def_dataset_method
# will be applied to the new dataset.
attr_reader :dataset_methods
#
# Array of plugin modules loaded by this class
#
# Sequel::Model.plugins
# # => [Sequel::Model, Sequel::Model::Associations]
attr_reader :plugins
# The primary key for the class. Sequel can determine this automatically for
# many databases, but not all, so you may need to set it manually. If not
# determined automatically, the default is :id.
attr_reader :primary_key
# Whether to raise an error instead of returning nil on a failure
# to save/create/save_changes/etc due to a validation failure or
# a before_* hook returning false.
attr_accessor :raise_on_save_failure
# Whether to raise an error when unable to typecast data for a column
# (default: true). This should be set to false if you want to use
# validations to display nice error messages to the user (e.g. most
# web applications). You can use the validates_not_string validations
# (from either the validation_helpers or validation_class_methods standard
# plugins) in connection with option to check for typecast failures for
# columns that aren't blobs or strings.
attr_accessor :raise_on_typecast_failure
# Whether to raise an error if an UPDATE or DELETE query related to
# a model instance does not modify exactly 1 row. If set to false,
# Sequel will not check the number of rows modified (default: true).
attr_accessor :require_modification
# Which columns are specifically restricted in a call to set/update/new/etc.
# (default: not set). Some columns are restricted regardless of
# this setting, such as the primary key column and columns in Model::RESTRICTED_SETTER_METHODS.
attr_reader :restricted_columns
# Should be the literal primary key column name if this Model's table has a simple primary key, or
# nil if the model has a compound primary key or no primary key.
attr_reader :simple_pk
# Should be the literal table name if this Model's dataset is a simple table (no select, order, join, etc.),
# or nil otherwise. This and simple_pk are used for an optimization in Model.[].
attr_reader :simple_table
# Whether new/set/update and their variants should raise an error
# if an invalid key is used. A key is invalid if no setter method exists
# for that key or the access to the setter method is restricted (e.g. due to it
# being a primary key field). If set to false, silently skip
# any key where the setter method doesn't exist or access to it is restricted.
attr_accessor :strict_param_setting
# Whether to typecast the empty string ('') to nil for columns that
# are not string or blob. In most cases the empty string would be the
# way to specify a NULL SQL value in string form (nil.to_s == ''),
# and an empty string would not usually be typecast correctly for other
# types, so the default is true.
attr_accessor :typecast_empty_string_to_nil
# Whether to typecast attribute values on assignment (default: true).
# If set to false, no typecasting is done, so it will be left up to the
# database to typecast the value correctly.
attr_accessor :typecast_on_assignment
# Whether to use a transaction by default when saving/deleting records (default: true).
# If you are sending database queries in before_* or after_* hooks, you shouldn't change
# the default setting without a good reason.
attr_accessor :use_transactions
# Returns the first record from the database matching the conditions.
# If a hash is given, it is used as the conditions. If another
# object is given, it finds the first record whose primary key(s) match
# the given argument(s). If no object is returned by the dataset, returns nil.
#
# Artist[1] # SELECT * FROM artists WHERE id = 1
# # => #<Artist {:id=>1, ...}>
#
# Artist[:name=>'Bob'] # SELECT * FROM artists WHERE (name = 'Bob') LIMIT 1
# # => #<Artist {:name=>'Bob', ...}>
def [](*args)
args = args.first if (args.size == 1)
args.is_a?(Hash) ? dataset[args] : primary_key_lookup(args)
end
# Clear the setter_methods cache
def clear_setter_methods_cache
@setter_methods = nil
end
# Returns the columns in the result set in their original order.
# Generally, this will use the columns determined via the database
# schema, but in certain cases (e.g. models that are based on a joined
# dataset) it will use <tt>Dataset#columns</tt> to find the columns.
#
# Artist.columns
# # => [:id, :name]
def columns
@columns || set_columns(dataset.naked.columns)
end
# Creates instance using new with the given values and block, and saves it.
#
# Artist.create(:name=>'Bob')
# # INSERT INTO artists (name) VALUES ('Bob')
#
# Artist.create do |a|
# a.name = 'Jim'
# end # INSERT INTO artists (name) VALUES ('Jim')
def create(values = {}, &block)
new(values, &block).save
end
# Returns the dataset associated with the Model class. Raises
# an +Error+ if there is no associated dataset for this class.
# In most cases, you don't need to call this directly, as Model
# proxies many dataset methods to the underlying dataset.
#
# Artist.dataset.all # SELECT * FROM artists
def dataset
@dataset || raise(Error, "No dataset associated with #{self}")
end
# Alias of set_dataset
def dataset=(ds)
set_dataset(ds)
end
# Returns the database associated with the Model class.
# If this model doesn't have a database associated with it,
# assumes the superclass's database, or the first object in
# Sequel::DATABASES. If no Sequel::Database object has
# been created, raises an error.
#
# Artist.db.transaction do # BEGIN
# Artist.create(:name=>'Bob')
# # INSERT INTO artists (name) VALUES ('Bob')
# end # COMMIT
def db
return @db if @db
@db = self == Model ? DATABASES.first : superclass.db
raise(Error, "No database associated with #{self}") unless @db
@db
end
# Sets the database associated with the Model class. If the
# model has an associated dataset, sets the model's dataset
# to a dataset on the new database with the same options
# used by the current dataset. This can be used directly on
# Sequel::Model to set the default database to be used
# by subclasses, or to override the database used for specific
# models:
#
# Sequel::Model.db = DB1
# Artist.db = DB2
def db=(db)
@db = db
set_dataset(db.dataset(@dataset.opts)) if @dataset
end
# Returns the cached schema information if available or gets it
# from the database. This is a hash where keys are column symbols
# and values are hashes of information related to the column. See
# <tt>Database#schema</tt>.
#
# Artist.db_schema
# # {:id=>{:type=>:integer, :primary_key=>true, ...},
# # :name=>{:type=>:string, :primary_key=>false, ...}}
def db_schema
@db_schema ||= get_db_schema
end
# If a block is given, define a method on the dataset (if the model currently has an dataset) with the given argument name using
# the given block. Also define a class method on the model that calls the
# dataset method. Stores the method name and block so that it can be reapplied if the model's
# dataset changes.
#
# If a block is not given, just define a class method on the model for each argument
# that calls the dataset method of the same argument name.
#
# # Add new dataset method and class method that calls it
# Artist.def_dataset_method(:by_name){order(:name)}
# Artist.filter(:name.like('A%')).by_name
# Artist.by_name.filter(:name.like('A%'))
#
# # Just add a class method that calls an existing dataset method
# Artist.def_dataset_method(:server!)
# Artist.server!(:server1)
def def_dataset_method(*args, &block)
raise(Error, "No arguments given") if args.empty?
if block
raise(Error, "Defining a dataset method using a block requires only one argument") if args.length > 1
meth = args.first
@dataset_methods[meth] = block
dataset.meta_def(meth, &block) if @dataset
end
args.each{|arg| instance_eval("def #{arg}(*args, &block); dataset.#{arg}(*args, &block) end", __FILE__, __LINE__) unless respond_to?(arg)}
end
# Finds a single record according to the supplied filter.
# You are encouraged to use Model.[] or Model.first instead of this method.
#
# Artist.find(:name=>'Bob')
# # SELECT * FROM artists WHERE (name = 'Bob') LIMIT 1
#
# Artist.find{name > 'M'}
# # SELECT * FROM artists WHERE (name > 'M') LIMIT 1
def find(*args, &block)
filter(*args, &block).first
end
# Like +find+ but invokes create with given conditions when record does not
# exist. Unlike +find+ in that the block used in this method is not passed
# to +find+, but instead is passed to +create+ only if +find+ does not
# return an object.
#
# Artist.find_or_create(:name=>'Bob')
# # SELECT * FROM artists WHERE (name = 'Bob') LIMIT 1
# # INSERT INTO artists (name) VALUES ('Bob')
#
# Artist.find_or_create(:name=>'Jim'){|a| a.hometown = 'Sactown'}
# # SELECT * FROM artists WHERE (name = 'Jim') LIMIT 1
# # INSERT INTO artists (name, hometown) VALUES ('Jim', 'Sactown')
def find_or_create(cond, &block)
find(cond) || create(cond, &block)
end
# If possible, set the dataset for the model subclass as soon as it
# is created. Also, make sure the inherited class instance variables
# are copied into the subclass.
#
# Sequel queries the database to get schema information as soon as
# a model class is created:
#
# class Artist < Sequel::Model # Causes schema query
# end
def inherited(subclass)
super
ivs = subclass.instance_variables.collect{|x| x.to_s}
EMPTY_INSTANCE_VARIABLES.each{|iv| subclass.instance_variable_set(iv, nil) unless ivs.include?(iv.to_s)}
INHERITED_INSTANCE_VARIABLES.each do |iv, dup|
next if ivs.include?(iv.to_s)
sup_class_value = instance_variable_get(iv)
sup_class_value = sup_class_value.dup if dup == :dup && sup_class_value
subclass.instance_variable_set(iv, sup_class_value)
end
unless ivs.include?("@dataset")
db
begin
if self == Model || !@dataset
subclass.set_dataset(subclass.implicit_table_name) unless subclass.name.empty?
elsif @dataset
subclass.set_dataset(@dataset.clone, :inherited=>true)
end
rescue
nil
end
end
end
# Returns the implicit table name for the model class, which is the demodulized,
# underscored, pluralized name of the class.
#
# Artist.implicit_table_name # => :artists
# Foo::ArtistAlias.implicit_table_name # => :artist_aliases
def implicit_table_name
pluralize(underscore(demodulize(name))).to_sym
end
# Initializes a model instance as an existing record. This constructor is
# used by Sequel to initialize model instances when fetching records.
# +load+ requires that values be a hash where all keys are symbols. It
# probably should not be used by external code.
def load(values)
new(values, true)
end
# Clear the setter_methods cache when a setter method is added
def method_added(meth)
clear_setter_methods_cache if meth.to_s =~ SETTER_METHOD_REGEXP
super
end
# Mark the model as not having a primary key. Not having a primary key
# can cause issues, among which is that you won't be able to update records.
#
# Artist.primary_key # => :id
# Artist.no_primary_key
# Artist.primary_key # => nil
def no_primary_key
clear_setter_methods_cache
@simple_pk = @primary_key = nil
end
# Loads a plugin for use with the model class, passing optional arguments
# to the plugin. If the plugin is a module, load it directly. Otherwise,
# require the plugin from either sequel/plugins/#{plugin} or
# sequel_#{plugin}, and then attempt to load the module using a
# the camelized plugin name under Sequel::Plugins.
def plugin(plugin, *args, &blk)
m = plugin.is_a?(Module) ? plugin : plugin_module(plugin)
unless @plugins.include?(m)
@plugins << m
m.apply(self, *args, &blk) if m.respond_to?(:apply)
include(m::InstanceMethods) if m.const_defined?("InstanceMethods")
extend(m::ClassMethods)if m.const_defined?("ClassMethods")
if m.const_defined?("DatasetMethods")
dataset.extend(m::DatasetMethods) if @dataset
dataset_method_modules << m::DatasetMethods
meths = m::DatasetMethods.public_instance_methods.reject{|x| NORMAL_METHOD_NAME_REGEXP !~ x.to_s}
def_dataset_method(*meths) unless meths.empty?
end
end
m.configure(self, *args, &blk) if m.respond_to?(:configure)
end
# Returns primary key attribute hash. If using a composite primary key
# value such be an array with values for each primary key in the correct
# order. For a standard primary key, value should be an object with a
# compatible type for the key. If the model does not have a primary key,
# raises an +Error+.
#
# Artist.primary_key_hash(1) # => {:id=>1}
# Artist.primary_key_hash([1, 2]) # => {:id1=>1, :id2=>2}
def primary_key_hash(value)
raise(Error, "#{self} does not have a primary key") unless key = @primary_key
case key
when Array
hash = {}
key.each_with_index{|k,i| hash[k] = value[i]}
hash
else
{key => value}
end
end
# Return a hash where the keys are qualified column references. Uses the given
# qualifier if provided, or the table_name otherwise. This is useful if you
# plan to join other tables to this table and you want the column references
# to be qualified.
#
# Artist.filter(Artist.qualified_primary_key_hash(1))
# # SELECT * FROM artists WHERE (artists.id = 1)
def qualified_primary_key_hash(value, qualifier=table_name)
h = primary_key_hash(value)
h.to_a.each{|k,v| h[SQL::QualifiedIdentifier.new(qualifier, k)] = h.delete(k)}
h
end
# Restrict the setting of the primary key(s) when using mass assignment (e.g. +set+). Because
# this is the default, this only make sense to use in a subclass where the
# parent class has used +unrestrict_primary_key+.
def restrict_primary_key
clear_setter_methods_cache
@restrict_primary_key = true
end
# Whether or not setting the primary key(s) when using mass assignment (e.g. +set+) is
# restricted, true by default.
def restrict_primary_key?
@restrict_primary_key
end
# Set the columns to allow when using mass assignment (e.g. +set+). Using this means that
# any columns not listed here will not be modified. If you have any virtual
# setter methods (methods that end in =) that you want to be used during
# mass assignment, they need to be listed here as well (without the =).
#
# It may be better to use a method such as +set_only+ instead of this in places where
# only certain columns may be allowed.
#
# Artist.set_allowed_columns(:name, :hometown)
# Artist.set(:name=>'Bob', :hometown=>'Sactown') # No Error
# Artist.set(:name=>'Bob', :records_sold=>30000) # Error
def set_allowed_columns(*cols)
clear_setter_methods_cache
@allowed_columns = cols
end
# Sets the dataset associated with the Model class. +ds+ can be a +Symbol+
# (specifying a table name in the current database), or a +Dataset+.
# If a dataset is used, the model's database is changed to the database of the given
# dataset. If a symbol is used, a dataset is created from the current
# database with the table name given. Other arguments raise an +Error+.
# Returns self.
#
# This changes the row_proc of the dataset to return
# model objects, extends the dataset with the dataset_method_modules,
# and defines methods on the dataset using the dataset_methods.
# It also attempts to determine the database schema for the model,
# based on the given dataset.
#
# Artist.set_dataset(:tbl_artists)
# Artist.set_dataset(DB[:artists])
def set_dataset(ds, opts={})
inherited = opts[:inherited]
@dataset = case ds
when Symbol
@simple_table = db.literal(ds)
db[ds]
when Dataset
@simple_table = nil
@db = ds.db
ds
else
raise(Error, "Model.set_dataset takes a Symbol or a Sequel::Dataset")
end
@dataset.row_proc = Proc.new{|r| load(r)}
@require_modification = Sequel::Model.require_modification.nil? ? @dataset.provides_accurate_rows_matched? : Sequel::Model.require_modification
if inherited
@simple_table = superclass.simple_table
@columns = @dataset.columns rescue nil
else
@dataset_method_modules.each{|m| @dataset.extend(m)} if @dataset_method_modules
@dataset_methods.each{|meth, block| @dataset.meta_def(meth, &block)} if @dataset_methods
end
@dataset.model = self if @dataset.respond_to?(:model=)
check_non_connection_error{@db_schema = (inherited ? superclass.db_schema : get_db_schema)}
self
end
# Sets the primary key for this model. You can use either a regular
# or a composite primary key. To not use a primary key, set to nil
# or use +no_primary_key+.
#
# class Person < Sequel::Model
# # regular key
# set_primary_key :person_id
# end
#
# class Tagging < Sequel::Model
# # composite key
# set_primary_key [:taggable_id, :tag_id]
# end
def set_primary_key(*key)
clear_setter_methods_cache
key = key.flatten
@simple_pk = key.length == 1 ? db.literal(key.first) : nil
@primary_key = (key.length == 1) ? key[0] : key
end
# Set the columns to restrict when using mass assignment (e.g. +set+). Using this means that
# attempts to call setter methods for the columns listed here will cause an
# exception or be silently skipped (based on the +strict_param_setting+ setting.
# If you have any virtual setter methods (methods that end in =) that you
# want not to be used during mass assignment, they need to be listed here as well (without the =).
#
# It may be better to use a method such as +set_except+ instead of this in places where
# certain columns are restricted. In general, it's better to have a whitelist approach
# where you specify only what is allowed, as opposed to a blacklist approach that this
# method uses, where everything is allowed other than what you restrict.
#
# Artist.set_restricted_column(:records_sold)
# Artist.set(:name=>'Bob', :hometown=>'Sactown') # No Error
# Artist.set(:name=>'Bob', :records_sold=>30000) # Error
def set_restricted_columns(*cols)
clear_setter_methods_cache
@restricted_columns = cols
end
# Cache of setter methods to allow by default, in order to speed up new/set/update instance methods.
def setter_methods
@setter_methods ||= if allowed_columns
allowed_columns.map{|x| "#{x}="}
else
meths = instance_methods.collect{|x| x.to_s}.grep(SETTER_METHOD_REGEXP) - RESTRICTED_SETTER_METHODS
meths -= Array(primary_key).map{|x| "#{x}="} if primary_key && restrict_primary_key?
meths -= restricted_columns.map{|x| "#{x}="} if restricted_columns
meths
end
end
# Shortcut for +def_dataset_method+ that is restricted to modifying the
# dataset's filter. Sometimes thought of as a scope, and like most dataset methods,
# they can be chained.
# For example:
#
# Topic.subset(:joes, :username.like('%joe%'))
# Topic.subset(:popular){num_posts > 100}
# Topic.subset(:recent){created_on > Date.today - 7}
#
# Allows you to do:
#
# Topic.joes.recent.popular
#
# to get topics with a username that includes joe that
# have more than 100 posts and were created less than
# 7 days ago.
#
# Both the args given and the block are passed to <tt>Dataset#filter</tt>.
def subset(name, *args, &block)
def_dataset_method(name){filter(*args, &block)}
end
# Returns name of primary table for the dataset. If the table for the dataset
# is aliased, returns the aliased name.
#
# Artist.table_name # => :artists
# Sequel::Model(:foo).table_name # => :foo
# Sequel::Model(:foo___bar).table_name # => :bar
def table_name
dataset.first_source_alias
end
# Allow the setting of the primary key(s) when using the mass assignment methods.
#
# Artist.set(:id=>1) # Error
# Artist.unrestrict_primary_key
# Artist.set(:id=>1) # No Error
def unrestrict_primary_key
clear_setter_methods_cache
@restrict_primary_key = false
end
private
# Yield to the passed block and swallow all errors other than DatabaseConnectionErrors.
def check_non_connection_error
begin
yield
rescue Sequel::DatabaseConnectionError
raise
rescue
nil
end
end
# Create a column accessor for a column with a method name that is hard to use in ruby code.
def def_bad_column_accessor(column)
overridable_methods_module.module_eval do
define_method(column){self[column]}
define_method("#{column}="){|v| self[column] = v}
end
end
# Create the column accessors. For columns that can be used as method names directly in ruby code,
# use a string to define the method for speed. For other columns names, use a block.
def def_column_accessor(*columns)
clear_setter_methods_cache
columns, bad_columns = columns.partition{|x| NORMAL_METHOD_NAME_REGEXP.match(x.to_s)}
bad_columns.each{|x| def_bad_column_accessor(x)}
im = instance_methods.collect{|x| x.to_s}
columns.each do |column|
meth = "#{column}="
overridable_methods_module.module_eval("def #{column}; self[:#{column}] end", __FILE__, __LINE__) unless im.include?(column.to_s)
overridable_methods_module.module_eval("def #{meth}(v); self[:#{column}] = v end", __FILE__, __LINE__) unless im.include?(meth)
end
end
# Get the schema from the database, fall back on checking the columns
# via the database if that will return inaccurate results or if
# it raises an error.
def get_db_schema(reload = false)
set_columns(nil)
return nil unless @dataset
schema_hash = {}
ds_opts = dataset.opts
single_table = ds_opts[:from] && (ds_opts[:from].length == 1) \
&& !ds_opts.include?(:join) && !ds_opts.include?(:sql)
get_columns = proc{check_non_connection_error{columns} || []}
if single_table && (schema_array = (db.schema(dataset.first_source_table, :reload=>reload) rescue nil))
schema_array.each{|k,v| schema_hash[k] = v}
if ds_opts.include?(:select)
# We don't remove the columns from the schema_hash,
# as it's possible they will be used for typecasting
# even if they are not selected.
cols = get_columns.call
cols.each{|c| schema_hash[c] ||= {}}
else
# Dataset is for a single table with all columns,
# so set the columns based on the order they were
# returned by the schema.
cols = schema_array.collect{|k,v| k}
set_columns(cols)
# Set the primary key(s) based on the schema information,
# if the schema information includes primary key information
if schema_array.all?{|k,v| v.has_key?(:primary_key)}
pks = schema_array.collect{|k,v| k if v[:primary_key]}.compact
pks.length > 0 ? set_primary_key(*pks) : no_primary_key
end
# Also set the columns for the dataset, so the dataset
# doesn't have to do a query to get them.
dataset.instance_variable_set(:@columns, cols)
end
else
# If the dataset uses multiple tables or custom sql or getting
# the schema raised an error, just get the columns and
# create an empty schema hash for it.
get_columns.call.each{|c| schema_hash[c] = {}}
end
schema_hash
end
# For the given opts hash and default name or :class option, add a
# :class_name option unless already present which contains the name
# of the class to use as a string. The purpose is to allow late
# binding to the class later using constantize.
def late_binding_class_option(opts, default)
case opts[:class]
when String, Symbol
# Delete :class to allow late binding
opts[:class_name] ||= opts.delete(:class).to_s
when Class
opts[:class_name] ||= opts[:class].name
end
opts[:class_name] ||= ((name || '').split("::")[0..-2] + [camelize(default)]).join('::')
end
# Module that the class includes that holds methods the class adds for column accessors and
# associations so that the methods can be overridden with +super+.
def overridable_methods_module
include(@overridable_methods_module = Module.new) unless @overridable_methods_module
@overridable_methods_module
end
# Returns the module for the specified plugin. If the module is not
# defined, the corresponding plugin required.
def plugin_module(plugin)
module_name = plugin.to_s.gsub(/(^|_)(.)/){|x| x[-1..-1].upcase}
if !Sequel::Plugins.const_defined?(module_name) ||
(Sequel.const_defined?(module_name) &&
Sequel::Plugins.const_get(module_name) == Sequel.const_get(module_name))
begin
Sequel.tsk_require "sequel/plugins/#{plugin}"
rescue LoadError => e
begin
Sequel.tsk_require "sequel_#{plugin}"
rescue LoadError => e2
e.message << "; #{e2.message}"
raise e
end
end
end
Sequel::Plugins.const_get(module_name)
end
# Find the row in the dataset that matches the primary key. Uses
# a static SQL optimization if the table and primary key are simple.
def primary_key_lookup(pk)
if t = simple_table and p = simple_pk
with_sql("SELECT * FROM #{t} WHERE #{p} = #{dataset.literal(pk)}").first
else
dataset[primary_key_hash(pk)]
end
end
# Set the columns for this model and create accessor methods for each column.
def set_columns(new_columns)
@columns = new_columns
def_column_accessor(*new_columns) if new_columns
@columns
end
# Add model methods that call dataset methods
DATASET_METHODS.each{|arg| class_eval("def #{arg}(*args, &block); dataset.#{arg}(*args, &block) end", __FILE__, __LINE__)}
# Returns a copy of the model's dataset with custom SQL
#
# Artist.fetch("SELECT * FROM artists WHERE name LIKE 'A%'")
# Artist.fetch("SELECT * FROM artists WHERE id = ?", 1)
alias fetch with_sql
end
# Sequel::Model instance methods that implement basic model functionality.
#
# * All of the methods in +HOOKS+ create instance methods that are called
# by Sequel when the appropriate action occurs. For example, when destroying
# a model object, Sequel will call +before_destroy+, do the destroy,
# and then call +after_destroy+.
# * The following instance_methods all call the class method of the same
# name: columns, dataset, db, primary_key, db_schema.
# * All of the methods in +BOOLEAN_SETTINGS+ create attr_writers allowing you
# to set values for the attribute. It also creates instnace getters returning
# the value of the setting. If the value has not yet been set, it
# gets the default value from the class by calling the class method of the same name.
module InstanceMethods
HOOKS.each{|h| class_eval("def #{h}; end", __FILE__, __LINE__)}
# Define instance method(s) that calls class method(s) of the
# same name, caching the result in an instance variable. Define
# standard attr_writer method for modifying that instance variable.
def self.class_attr_overridable(*meths) # :nodoc:
meths.each{|meth| class_eval("def #{meth}; !defined?(@#{meth}) ? (@#{meth} = self.class.#{meth}) : @#{meth} end", __FILE__, __LINE__)}
attr_writer(*meths)
end
# Define instance method(s) that calls class method(s) of the
# same name. Replaces the construct:
#
# define_method(meth){self.class.send(meth)}
def self.class_attr_reader(*meths) # :nodoc:
meths.each{|meth| class_eval("def #{meth}; model.#{meth} end", __FILE__, __LINE__)}
end
private_class_method :class_attr_overridable, :class_attr_reader
class_attr_reader :columns, :db, :primary_key, :db_schema
class_attr_overridable *BOOLEAN_SETTINGS
# The hash of attribute values. Keys are symbols with the names of the
# underlying database columns.
#
# Artist.new(:name=>'Bob').values # => {:name=>'Bob'}
# Artist[1].values # => {:id=>1, :name=>'Jim', ...}
attr_reader :values
# Creates new instance and passes the given values to set.
# If a block is given, yield the instance to the block unless
# from_db is true.
# This method runs the after_initialize hook after
# it has optionally yielded itself to the block.
#
# Arguments:
# values :: should be a hash to pass to set.
# from_db :: should only be set by <tt>Model.load</tt>, forget it exists.
#
# Artist.new(:name=>'Bob')
#
# Artist.new do |a|
# a.name = 'Bob'
# end
def initialize(values = {}, from_db = false)
if from_db
@new = false
set_values(values)
else
@values = {}
@new = true
@modified = true
set(values)
changed_columns.clear
yield self if block_given?
end
after_initialize
end
# Returns value of the column's attribute.
#
# Artist[1][:id] #=> 1
def [](column)
@values[column]
end
# Sets the value for the given column. If typecasting is enabled for
# this object, typecast the value based on the column's type.
# If this a a new record or the typecasted value isn't the same
# as the current value for the column, mark the column as changed.
#
# a = Artist.new
# a[:name] = 'Bob'
# a.values #=> {:name=>'Bob'}
def []=(column, value)
# If it is new, it doesn't have a value yet, so we should
# definitely set the new value.
# If the column isn't in @values, we can't assume it is
# NULL in the database, so assume it has changed.
v = typecast_value(column, value)
if new? || !@values.include?(column) || v != (c = @values[column]) || v.class != c.class
changed_columns << column unless changed_columns.include?(column)
@values[column] = v
end
end
# Alias of eql?
def ==(obj)
eql?(obj)
end
# If pk is not nil, true only if the objects have the same class and pk.
# If pk is nil, false.
#
# Artist[1] === Artist[1] # true
# Artist.new === Artist.new # false
# Artist[1].set(:name=>'Bob') == Artist[1] # => true
def ===(obj)
pk.nil? ? false : (obj.class == model) && (obj.pk == pk)
end
# class is defined in Object, but it is also a keyword,
# and since a lot of instance methods call class methods,
# this alias makes it so you can use model instead of
# self.class.
#
# Artist.new.model # => Artist
alias_method :model, :class
# The autoincrementing primary key for this model object. Should be
# overridden if you have a composite primary key with one part of it
# being autoincrementing.
def autoincrementing_primary_key
primary_key
end
# The columns that have been updated. This isn't completely accurate,
# as it could contain columns whose values have not changed.
#
# a = Artist[1]
# a.changed_columns # => []
# a.name = 'Bob'
# a.changed_columns # => [:name]
def changed_columns
@changed_columns ||= []
end
# Deletes and returns +self+. Does not run destroy hooks.
# Look into using +destroy+ instead.
#
# Artist[1].delete # DELETE FROM artists WHERE (id = 1)
# # => #<Artist {:id=>1, ...}>
def delete
_delete
self
end
# Like delete but runs hooks before and after delete.
# If before_destroy returns false, returns false without
# deleting the object the the database. Otherwise, deletes
# the item from the database and returns self. Uses a transaction
# if use_transactions is true or if the :transaction option is given and
# true.
#
# Artist[1].destroy # BEGIN; DELETE FROM artists WHERE (id = 1); COMMIT;
# # => #<Artist {:id=>1, ...}>
def destroy(opts = {})
checked_save_failure(opts){checked_transaction(opts){_destroy(opts)}}
end
# Iterates through all of the current values using each.
#
# Album[1].each{|k, v| puts "#{k} => #{v}"}
# # id => 1
# # name => 'Bob'
def each(&block)
@values.each(&block)
end
# Compares model instances by values.
#
# Artist[1] == Artist[1] # => true
# Artist.new == Artist.new # => true
# Artist[1].set(:name=>'Bob') == Artist[1] # => false
def eql?(obj)
(obj.class == model) && (obj.values == @values)
end
# Returns the validation errors associated with this object.
# See +Errors+.
def errors
@errors ||= Errors.new
end
# Returns true when current instance exists, false otherwise.
# Generally an object that isn't new will exist unless it has
# been deleted.
#
# Artist[1].exists? # SELECT 1 FROM artists WHERE (id = 1)
# # => true
def exists?
!this.get(1).nil?
end
# Value that should be unique for objects with the same class and pk (if pk is not nil), or
# the same class and values (if pk is nil).
#
# Artist[1].hash == Artist[1].hash # true
# Artist[1].set(:name=>'Bob').hash == Artist[1].hash # true
# Artist.new.hash == Artist.new.hash # true
# Artist.new(:name=>'Bob').hash == Artist.new.hash # false
def hash
[model, pk.nil? ? @values.sort_by{|k,v| k.to_s} : pk].hash
end
# Returns value for the :id attribute, even if the primary key is
# not id. To get the primary key value, use +pk+.
#
# Artist[1].id # => 1
def id
@values[:id]
end
# Returns a string representation of the model instance including
# the class name and values.
def inspect
"#<#{model.name} @values=#{inspect_values}>"
end
# Returns the keys in +values+. May not include all column names.
#
# Artist.new.keys # => []
# Artist.new(:name=>'Bob').keys # => [:name]
# Artist[1].keys # => [:id, :name]
def keys
@values.keys
end
# Refresh this record using +for_update+ unless this is a new record. Returns self.
# This can be used to make sure no other process is updating the record at the
# same time.
#
# a = Artist[1]
# Artist.db.transaction do
# a.lock!
# a.update(...)
# end
def lock!
new? ? self : _refresh(this.for_update)
end
# Remove elements of the model object that make marshalling fail. Returns self.
#
# a = Artist[1]
# a.marshallable!
# Marshal.dump(a)
def marshallable!
@this = nil
self
end
# Explicitly mark the object as modified, so +save_changes+/+update+ will
# run callbacks even if no columns have changed.
#
# a = Artist[1]
# a.save_changes # No callbacks run, as no changes
# a.modified!
# a.save_changes # Callbacks run, even though no changes made
def modified!
@modified = true
end
# Whether this object has been modified since last saved, used by
# save_changes to determine whether changes should be saved. New
# values are always considered modified.
#
# a = Artist[1]
# a.modified? # => false
# a.set(:name=>'Jim')
# a.modified # => true
def modified?
@modified || !changed_columns.empty?
end
# Returns true if the current instance represents a new record.
#
# Artist.new.new? # => true
# Artist[1].new? # => false
def new?
@new
end
# Returns the primary key value identifying the model instance.
# Raises an error if this model does not have a primary key.
# If the model has a composite primary key, returns an array of values.
#
# Artist[1].pk # => 1
# Artist[[1, 2]].pk # => [1, 2]
def pk
raise(Error, "No primary key is associated with this model") unless key = primary_key
key.is_a?(Array) ? key.map{|k| @values[k]} : @values[key]
end
# Returns a hash identifying mapping the receivers primary key column(s) to their values.
#
# Artist[1].pk_hash # => {:id=>1}
# Artist[[1, 2]].pk_hash # => {:id1=>1, :id2=>2}
def pk_hash
model.primary_key_hash(pk)
end
# Reloads attributes from database and returns self. Also clears all
# changed_columns information. Raises an +Error+ if the record no longer
# exists in the database.
#
# a = Artist[1]
# a.name = 'Jim'
# a.refresh
# a.name # => 'Bob'
def refresh
_refresh(this)
end
# Alias of refresh, but not aliased directly to make overriding in a plugin easier.
def reload
refresh
end
# Creates or updates the record, after making sure the record
# is valid and before hooks execute successfully. Fails if:
#
# * the record is not valid, or
# * before_save returns false, or
# * the record is new and before_create returns false, or
# * the record is not new and before_update returns false.
#
# If +save+ fails and either raise_on_save_failure or the
# :raise_on_failure option is true, it raises ValidationFailed
# or BeforeHookFailed. Otherwise it returns nil.
#
# If it succeeds, it returns self.
#
# You can provide an optional list of columns to update, in which
# case it only updates those columns.
#
# Takes the following options:
#
# * :changed - save all changed columns, instead of all columns or the columns given
# * :transaction - set to true or false to override the current
# use_transactions setting
# * :validate - set to false to skip validation
# * :raise_on_failure - set to true or false to override the current
# raise_on_save_failure setting
def save(*columns)
opts = columns.last.is_a?(Hash) ? columns.pop : {}
if opts[:validate] != false and !valid?(opts)
raise(ValidationFailed.new(errors)) if raise_on_failure?(opts)
return
end
checked_save_failure(opts){checked_transaction(opts){_save(columns, opts)}}
end
# Saves only changed columns if the object has been modified.
# If the object has not been modified, returns nil. If unable to
# save, returns false unless +raise_on_save_failure+ is true.
#
# a = Artist[1]
# a.save_changes # => nil
# a.name = 'Jim'
# a.save_changes # UPDATE artists SET name = 'Bob' WHERE (id = 1)
# # => #<Artist {:id=>1, :name=>'Jim', ...}
def save_changes(opts={})
save(opts.merge(:changed=>true)) || false if modified?
end
# Updates the instance with the supplied values with support for virtual
# attributes, raising an exception if a value is used that doesn't have
# a setter method (or ignoring it if <tt>strict_param_setting = false</tt>).
# Does not save the record.
#
# artist.set(:name=>'Jim')
# artist.name # => 'Jim'
def set(hash)
set_restricted(hash, nil, nil)
end
# Set all values using the entries in the hash, ignoring any setting of
# allowed_columns or restricted columns in the model.
#
# Artist.set_restricted_columns(:name)
# artist.set_all(:name=>'Jim')
# artist.name # => 'Jim'
def set_all(hash)
set_restricted(hash, false, false)
end
# Set all values using the entries in the hash, except for the keys
# given in except.
#
# artist.set_except({:name=>'Jim'}, :hometown)
# artist.name # => 'Jim'
def set_except(hash, *except)
set_restricted(hash, false, except.flatten)
end
# For each of the fields in the given array +fields+, call the setter
# method with the value of that +hash+ entry for the field. Returns self.
#
# artist.set_fields({:name=>'Jim'}, :name)
# artist.name # => 'Jim'
#
# artist.set_fields({:hometown=>'LA'}, :name)
# artist.name # => nil
# artist.hometown # => 'Sac'
def set_fields(hash, fields)
fields.each{|f| send("#{f}=", hash[f])}
self
end
# Set the values using the entries in the hash, only if the key
# is included in only.
#
# artist.set_only({:name=>'Jim'}, :name)
# artist.name # => 'Jim'
#
# artist.set_only({:hometown=>'LA'}, :name) # Raise error
def set_only(hash, *only)
set_restricted(hash, only.flatten, false)
end
# Clear the setter_methods cache when a method is added
def singleton_method_added(meth)
@singleton_setter_added = true if meth.to_s =~ SETTER_METHOD_REGEXP
super
end
# Returns (naked) dataset that should return only this instance.
#
# Artist[1].this
# # SELECT * FROM artists WHERE (id = 1) LIMIT 1
def this
@this ||= model.dataset.filter(pk_hash).limit(1).naked
end
# Runs set with the passed hash and then runs save_changes.
#
# artist.update(:name=>'Jim') # UPDATE artists SET name = 'Jim' WHERE (id = 1)
def update(hash)
update_restricted(hash, nil, nil)
end
# Update all values using the entries in the hash, ignoring any setting of
# allowed_columns or restricted columns in the model.
#
# Artist.set_restricted_columns(:name)
# artist.update_all(:name=>'Jim') # UPDATE artists SET name = 'Jim' WHERE (id = 1)
def update_all(hash)
update_restricted(hash, false, false)
end
# Update all values using the entries in the hash, except for the keys
# given in except.
#
# artist.update_except({:name=>'Jim'}, :hometown) # UPDATE artists SET name = 'Jim' WHERE (id = 1)
def update_except(hash, *except)
update_restricted(hash, false, except.flatten)
end
# Update the instances values by calling +set_fields+ with the +hash+
# and +fields+, then save any changes to the record. Returns self.
#
# artist.update_fields({:name=>'Jim'}, :name)
# # UPDATE artists SET name = 'Jim' WHERE (id = 1)
#
# artist.update_fields({:hometown=>'LA'}, :name)
# # UPDATE artists SET name = NULL WHERE (id = 1)
def update_fields(hash, fields)
set_fields(hash, fields)
save_changes
end
# Update the values using the entries in the hash, only if the key
# is included in only.
#
# artist.update_only({:name=>'Jim'}, :name)
# # UPDATE artists SET name = 'Jim' WHERE (id = 1)
#
# artist.update_only({:hometown=>'LA'}, :name) # Raise Error
def update_only(hash, *only)
update_restricted(hash, only.flatten, false)
end
# Validates the object. If the object is invalid, errors should be added
# to the errors attribute. By default, does nothing, as all models
# are valid by default. See the {"Model Validations" guide}[link:files/doc/validations_rdoc.html].
# for details about validation. Should not be called directly by
# user code, call <tt>valid?</tt> instead to check if an object
# is valid.
def validate
end
# Validates the object and returns true if no errors are reported.
#
# artist(:name=>'Valid').valid? # => true
# artist(:name=>'Invalid').valid? # => false
# artist.errors.full_messages # => ['name cannot be Invalid']
def valid?(opts = {})
errors.clear
if before_validation == false
raise_hook_failure(:validation) if raise_on_failure?(opts)
return false
end
validate
after_validation
errors.empty?
end
private
# Actually do the deletion of the object's dataset.
def _delete
n = _delete_dataset.delete
raise(NoExistingObject, "Attempt to delete object did not result in a single row modification (Rows Deleted: #{n}, SQL: #{_delete_dataset.delete_sql})") if require_modification && n != 1
n
end
# The dataset to use when deleting the object. The same as the object's
# dataset by default.
def _delete_dataset
this
end
# Internal destroy method, separted from destroy to
# allow running inside a transaction
def _destroy(opts)
raise_hook_failure(:destroy) if before_destroy == false
_destroy_delete
after_destroy
self
end
# Internal delete method to call when destroying an object,
# separated from delete to allow you to override destroy's version
# without affecting delete.
def _destroy_delete
delete
end
# Insert the record into the database, returning the primary key if
# the record should be refreshed from the database.
def _insert
ds = _insert_dataset
if ds.respond_to?(:insert_select) and h = ds.insert_select(@values)
@values = h
nil
else
iid = ds.insert(@values)
# if we have a regular primary key and it's not set in @values,
# we assume it's the last inserted id
if (pk = autoincrementing_primary_key) && pk.is_a?(Symbol) && !@values[pk]
@values[pk] = iid
end
pk
end
end
# The dataset to use when inserting a new object. The same as the model's
# dataset by default.
def _insert_dataset
model.dataset
end
# Refresh using a particular dataset, used inside save to make sure the same server
# is used for reading newly inserted values from the database
def _refresh(dataset)
set_values(dataset.first || raise(Error, "Record not found"))
changed_columns.clear
self
end
# Internal version of save, split from save to allow running inside
# it's own transaction.
def _save(columns, opts)
raise_hook_failure(:save) if before_save == false
if new?
raise_hook_failure(:create) if before_create == false
pk = _insert
@this = nil
@new = false
@was_new = true
after_create
after_save
@was_new = nil
pk ? _save_refresh : changed_columns.clear
else
raise_hook_failure(:update) if before_update == false
if columns.empty?
@columns_updated = if opts[:changed]
@values.reject{|k,v| !changed_columns.include?(k)}
else
_save_update_all_columns_hash
end
changed_columns.clear
else # update only the specified columns
@columns_updated = @values.reject{|k, v| !columns.include?(k)}
changed_columns.reject!{|c| columns.include?(c)}
end
_update_columns(@columns_updated)
@this = nil
after_update
after_save
@columns_updated = nil
end
@modified = false
self
end
# Refresh the object after saving it, used to get
# default values of all columns. Separated from _save so it
# can be overridden to avoid the refresh.
def _save_refresh
_refresh(this.opts[:server] ? this : this.server(:default))
end
# Return a hash of values used when saving all columns of an
# existing object (i.e. not passing specific columns to save
# or using update/save_changes). Defaults to all of the
# object's values except unmodified primary key columns, as some
# databases don't like you setting primary key values even
# to their existing values.
def _save_update_all_columns_hash
v = @values.dup
Array(primary_key).each{|x| v.delete(x) unless changed_columns.include?(x)}
v
end
# Call _update with the given columns, if any are present.
# Plugins can override this method in order to update with
# additional columns, even when the column hash is initially empty.
def _update_columns(columns)
_update(columns) unless columns.empty?
end
# Update this instance's dataset with the supplied column hash.
def _update(columns)
n = _update_dataset.update(columns)
raise(NoExistingObject, "Attempt to update object did not result in a single row modification (SQL: #{_update_dataset.update_sql(columns)})") if require_modification && n != 1
n
end
# The dataset to use when updating an object. The same as the object's
# dataset by default.
def _update_dataset
this
end
# If not raising on failure, check for BeforeHookFailed
# being raised by yielding and swallow it.
def checked_save_failure(opts)
if raise_on_failure?(opts)
yield
else
begin
yield
rescue BeforeHookFailed
nil
end
end
end
# If transactions should be used, wrap the yield in a transaction block.
def checked_transaction(opts={})
use_transaction?(opts) ? db.transaction(opts){yield} : yield
end
# Default inspection output for the values hash, overwrite to change what #inspect displays.
def inspect_values
@values.inspect
end
# Whether to raise or return false if this action fails. If the
# :raise_on_failure option is present in the hash, use that, otherwise,
# fallback to the object's raise_on_save_failure (if set), or
# class's default (if not).
def raise_on_failure?(opts)
opts.fetch(:raise_on_failure, raise_on_save_failure)
end
# Raise an error appropriate to the hook type. May be swallowed by
# checked_save_failure depending on the raise_on_failure? setting.
def raise_hook_failure(type)
raise BeforeHookFailed, "one of the before_#{type} hooks returned false"
end
# Set the columns, filtered by the only and except arrays.
def set_restricted(hash, only, except)
meths = if only.nil? && except.nil? && !@singleton_setter_added
model.setter_methods
else
setter_methods(only, except)
end
strict = strict_param_setting
hash.each do |k,v|
m = "#{k}="
if meths.include?(m)
send(m, v)
elsif strict
raise Error, "method #{m} doesn't exist or access is restricted to it"
end
end
self
end
# Replace the current values with hash.
def set_values(hash)
@values = hash
end
# Returns all methods that can be used for attribute
# assignment (those that end with =), modified by the only
# and except arguments:
#
# * only
# * false - Don't modify the results
# * nil - if the model has allowed_columns, use only these, otherwise, don't modify
# * Array - allow only the given methods to be used
# * except
# * false - Don't modify the results
# * nil - if the model has restricted_columns, remove these, otherwise, don't modify
# * Array - remove the given methods
#
# only takes precedence over except, and if only is not used, certain methods are always
# restricted (RESTRICTED_SETTER_METHODS). The primary key is restricted by default as
# well, see Model.unrestrict_primary_key to change this.
def setter_methods(only, except)
only = only.nil? ? model.allowed_columns : only
except = except.nil? ? model.restricted_columns : except
if only
only.map{|x| "#{x}="}
else
meths = methods.collect{|x| x.to_s}.grep(SETTER_METHOD_REGEXP) - RESTRICTED_SETTER_METHODS
meths -= Array(primary_key).map{|x| "#{x}="} if primary_key && model.restrict_primary_key?
meths -= except.map{|x| "#{x}="} if except
meths
end
end
# Typecast the value to the column's type if typecasting. Calls the database's
# typecast_value method, so database adapters can override/augment the handling
# for database specific column types.
def typecast_value(column, value)
return value unless typecast_on_assignment && db_schema && (col_schema = db_schema[column])
value = nil if value == '' and typecast_empty_string_to_nil and col_schema[:type] and ![:string, :blob].include?(col_schema[:type])
raise(InvalidValue, "nil/NULL is not allowed for the #{column} column") if raise_on_typecast_failure && value.nil? && (col_schema[:allow_null] == false)
begin
model.db.typecast_value(col_schema[:type], value)
rescue InvalidValue
raise_on_typecast_failure ? raise : value
end
end
# Set the columns, filtered by the only and except arrays.
def update_restricted(hash, only, except)
set_restricted(hash, only, except)
save_changes
end
# Whether to use a transaction for this action. If the :transaction
# option is present in the hash, use that, otherwise, fallback to the
# object's default (if set), or class's default (if not).
def use_transaction?(opts = {})
opts.fetch(:transaction, use_transactions)
end
end
# Dataset methods are methods that the model class extends its dataset with in
# the call to set_dataset.
module DatasetMethods
# The model class associated with this dataset
#
# Artist.dataset.model # => Artist
attr_accessor :model
# Destroy each row in the dataset by instantiating it and then calling
# destroy on the resulting model object. This isn't as fast as deleting
# the dataset, which does a single SQL call, but this runs any destroy
# hooks on each object in the dataset.
#
# Artist.dataset.destroy
# # DELETE FROM artists WHERE (id = 1)
# # DELETE FROM artists WHERE (id = 2)
# # ...
def destroy
pr = proc{all{|r| r.destroy}.length}
model.use_transactions ? @db.transaction(&pr) : pr.call
end
# This allows you to call +to_hash+ without any arguments, which will
# result in a hash with the primary key value being the key and the
# model object being the value.
#
# Artist.dataset.to_hash # SELECT * FROM artists
# # => {1=>#<Artist {:id=>1, ...}>,
# # 2=>#<Artist {:id=>2, ...}>,
# # ...}
def to_hash(key_column=nil, value_column=nil)
if key_column
super
else
raise(Sequel::Error, "No primary key for model") unless model and pk = model.primary_key
super(pk, value_column)
end
end
end
extend ClassMethods
plugin self
end
end