Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Minor RDoc updates

  • Loading branch information...
commit c1a6b68e9ba6555ba2b43d17602ac316256df898 1 parent e5a21f2
@jeremyevans authored
View
4 lib/sequel/metaprogramming.rb
@@ -2,6 +2,10 @@ module Sequel
# Contains meta_def method for adding methods to objects via blocks, used by some of Sequel's classes and objects.
module Metaprogramming
# Define a method with the given name and block body on the receiver.
+ #
+ # ds = DB[:items]
+ # ds.meta_def(:x){42}
+ # ds.x # => 42
def meta_def(name, &block)
(class << self; self end).send(:define_method, name, &block)
end
View
56 lib/sequel/model.rb
@@ -2,20 +2,38 @@
module Sequel
# Lets you create a Model subclass with its dataset already set.
- # source can be an existing dataset or a symbol (in which case
- # it will create a dataset using the default database with
- # the given symbol as the table name).
+ # +source+ should be an instance of one of the following classes:
#
- # The purpose of this method is to set the dataset automatically
+ # Database :: Sets the database for this model to +source+.
+ # Generally only useful when subclassing directly
+ # from the returned class, where the name of the
+ # subclass sets the table name (which is combined
+ # with the +Database+ in +source+ to create the
+ # dataset to use)
+ # Dataset :: Sets the dataset for this model to +source+.
+ # Symbol :: Sets the table name for this model to +source+. The
+ # class will use the default database for model
+ # classes in order to create the dataset.
+ #
+ # The purpose of this method is to set the dataset/database automatically
# for a model class, if the table name doesn't match the implicit
# name. This is neater than using set_dataset inside the class,
- # doesn't require a bogus query for the schema, and allows
- # it to work correctly in a system that uses code reloading.
+ # doesn't require a bogus query for the schema.
#
- # Example:
+ # # Using a symbol
# class Comment < Sequel::Model(:something)
# table_name # => :something
# end
+ #
+ # # Using a dataset
+ # class Comment < Sequel::Model(DB1[:something])
+ # dataset # => DB1[:something]
+ # end
+ #
+ # # Using a database
+ # class Comment < Sequel::Model(DB1)
+ # dataset # => DB1[:comments]
+ # end
def self.Model(source)
Model::ANONYMOUS_MODEL_CLASSES[source] ||= if source.is_a?(Database)
c = Class.new(Model)
@@ -26,20 +44,20 @@ def self.Model(source)
end
end
- # Sequel::Model is an object relational mapper built on top of Sequel core. Each
+ # <tt>Sequel::Model</tt> is an object relational mapper built on top of Sequel core. Each
# model class is backed by a dataset instance, and many dataset methods can be
# called directly on the class. Model datasets return rows as model instances,
# which have fairly standard ORM instance behavior.
#
- # Sequel::Model is built completely out of plugins, the only method not part of a
+ # <tt>Sequel::Model</tt> is built completely out of plugins, the only method not part of a
# plugin is the plugin method itself. Plugins can override any class, instance, or
# dataset method defined by a previous plugin and call super to get the default
# behavior.
#
- # You can set the SEQUEL_NO_ASSOCIATIONS constant or environment variable to
+ # You can set the +SEQUEL_NO_ASSOCIATIONS+ constant or environment variable to
# make Sequel not load the associations plugin by default.
class Model
- # Map that stores model classes created with Sequel::Model(), to allow the reopening
+ # Map that stores model classes created with <tt>Sequel::Model()</tt>, to allow the reopening
# of classes when dealing with code reloading.
ANONYMOUS_MODEL_CLASSES = {}
@@ -54,24 +72,24 @@ class Model
BOOLEAN_SETTINGS = [:typecast_empty_string_to_nil, :typecast_on_assignment, :strict_param_setting, :raise_on_save_failure, :raise_on_typecast_failure, :require_modification, :use_transactions]
# Hooks that are called before an action. Can return false to not do the action. When
- # overriding these, it is recommended to call super as the last line of your method,
+ # overriding these, it is recommended to call +super+ as the last line of your method,
# so later hooks are called before earlier hooks.
BEFORE_HOOKS = [:before_create, :before_update, :before_save, :before_destroy, :before_validation]
# Hooks that are called after an action. When overriding these, it is recommended to call
- # super on the first line of your method, so later hooks are called before earlier hooks.
+ # +super+ on the first line of your method, so later hooks are called after earlier hooks.
AFTER_HOOKS = [:after_initialize, :after_create, :after_update, :after_save, :after_destroy, :after_validation]
# Empty instance methods to create that the user can override to get hook/callback behavior.
# Just like any other method defined by Sequel, if you override one of these, you should
- # call super to get the default behavior (while empty by default, they can also be defined
+ # call +super+ to get the default behavior (while empty by default, they can also be defined
# by plugins). See the {"Model Hooks" guide}[link:files/doc/model_hooks_rdoc.html] for
# more detail on hooks.
HOOKS = BEFORE_HOOKS + AFTER_HOOKS
- # Class instance variables that are inherited in subclasses. If the value is :dup, dup is called
+ # Class instance variables that are inherited in subclasses. If the value is <tt>:dup</tt>, dup is called
# on the superclass's instance variable when creating the instance variable in the subclass.
- # If the value is nil, the superclass's instance variable is used directly in the subclass.
+ # If the value is +nil+, the superclass's instance variable is used directly in the subclass.
INHERITED_INSTANCE_VARIABLES = {:@allowed_columns=>:dup, :@dataset_methods=>:dup,
:@dataset_method_modules=>:dup, :@primary_key=>nil, :@use_transactions=>nil,
:@raise_on_save_failure=>nil, :@require_modification=>nil,
@@ -80,8 +98,8 @@ class Model
:@typecast_empty_string_to_nil=>nil, :@typecast_on_assignment=>nil,
:@raise_on_typecast_failure=>nil, :@plugins=>:dup}
- # Regexp that determines if a method name is normal in the sense that
- # it could be called directly in ruby code without using send. Used to
+ # Regular expression that determines if a method name is normal in the sense that
+ # it could be used literally in ruby code without using send. Used to
# avoid problems when using eval with a string to define methods.
NORMAL_METHOD_NAME_REGEXP = /\A[A-Za-z_][A-Za-z0-9_]*\z/
@@ -116,7 +134,7 @@ class Model
end
# The setter methods (methods ending with =) that are never allowed
- # to be called automatically via set/update/new/etc..
+ # to be called automatically via +set+/+update+/+new+/etc..
RESTRICTED_SETTER_METHODS = instance_methods.map{|x| x.to_s}.grep(SETTER_METHOD_REGEXP)
end
end
View
66 lib/sequel/sql.rb
@@ -1,7 +1,7 @@
module Sequel
if RUBY_VERSION < '1.9.0'
- # If on Ruby 1.8, create a Sequel::BasicObject class that is similar to the
- # the Ruby 1.9 BasicObject class. This is used in a few places where proxy
+ # If on Ruby 1.8, create a <tt>Sequel::BasicObject</tt> class that is similar to the
+ # the Ruby 1.9 +BasicObject+ class. This is used in a few places where proxy
# objects are needed that respond to any method call.
class BasicObject
# The instance methods to not remove from the class when removing
@@ -10,26 +10,26 @@ class BasicObject
# Remove all but the most basic instance methods from the class. A separate
# method so that it can be called again if necessary if you load libraries
- # after Sequel that add instance methods to Object.
+ # after Sequel that add instance methods to +Object+.
def self.remove_methods!
((private_instance_methods + instance_methods) - KEEP_METHODS).each{|m| undef_method(m)}
end
remove_methods!
end
else
- # If on 1.9, create a Sequel::BasicObject class that is just like the
- # default BasicObject class, except that missing constants are resolved in
- # Object. This allows the virtual row support to work with classes
+ # If on 1.9, create a <tt>Sequel::BasicObject</tt> class that is just like the
+ # default +BasicObject+ class, except that missing constants are resolved in
+ # +Object+. This allows the virtual row support to work with classes
# without prefixing them with ::, such as:
#
# DB[:bonds].filter{maturity_date > Time.now}
class BasicObject < ::BasicObject
- # Lookup missing constants in ::Object
+ # Lookup missing constants in <tt>::Object</tt>
def self.const_missing(name)
::Object.const_get(name)
end
- # No-op method on ruby 1.9, which has a real BasicObject class.
+ # No-op method on ruby 1.9, which has a real +BasicObject+ class.
def self.remove_methods!
end
end
@@ -45,17 +45,22 @@ module SQL
### Parent Classes ###
- # Classes/Modules aren't an alphabetical order due to the fact that
+ # Classes/Modules aren't in alphabetical order due to the fact that
# some reference constants defined in others at load time.
- # Base class for all SQL fragments
+ # Base class for all SQL expression objects.
class Expression
- # all instance variables declared to be readers are to be used for comparison.
+ # Expression objects are assumed to be value objects, where their
+ # attribute values can't change after assignment. In order to make
+ # it easy to define equality and hash methods, subclass
+ # instances assume that the only values that affect the results of
+ # such methods are the values of the object's attributes.
def self.attr_reader(*args)
super
comparison_attrs.concat args
end
+ # All attributes used for equality and hash methods.
def self.comparison_attrs
@comparison_attrs ||= self == Expression ? [] : superclass.comparison_attrs.clone
end
@@ -68,7 +73,7 @@ def self.to_s_method(meth, args=:self) # :nodoc:
end
private_class_method :to_s_method
- # Alias of eql?
+ # Alias of <tt>eql?</tt>
def ==(other)
eql?(other)
end
@@ -76,7 +81,7 @@ def ==(other)
# Returns true if the receiver is the same expression as the
# the +other+ expression.
def eql?(other)
- other.is_a?(self.class) && !self.class.comparison_attrs.find {|a| send(a) != other.send(a)}
+ other.is_a?(self.class) && !self.class.comparison_attrs.find{|a| send(a) != other.send(a)}
end
# Make sure that the hash value is the same if the attributes are the same.
@@ -90,13 +95,12 @@ def inspect
"#<#{self.class} #{instance_variables.map{|iv| "#{iv}=>#{instance_variable_get(iv).inspect}"}.join(', ')}>"
end
- # Returns self, because SQL::Expression already acts like
- # LiteralString.
+ # Returns +self+, because <tt>SQL::Expression</tt> already acts like +LiteralString+.
def lit
self
end
- # Alias of to_s
+ # Alias of +to_s+
def sql_literal(ds)
to_s(ds)
end
@@ -104,11 +108,10 @@ def sql_literal(ds)
# Represents a complex SQL expression, with a given operator and one
# or more attributes (which may also be ComplexExpressions, forming
- # a tree). This class is the backbone of the blockless filter support in
- # Sequel.
+ # a tree). This class is the backbone of Sequel's ruby expression DSL.
#
# This is an abstract class that is not that useful by itself. The
- # subclasses BooleanExpression, NumericExpression, and StringExpression
+ # subclasses +BooleanExpression+, +NumericExpression+, and +StringExpression+
# define the behavior of the DSL via operators.
class ComplexExpression < Expression
# A hash of the opposite for each operator symbol, used for inverting
@@ -120,16 +123,16 @@ class ComplexExpression < Expression
:'!~*' => :'~*', :NOT => :NOOP, :NOOP => :NOT, :ILIKE => :'NOT ILIKE',
:'NOT ILIKE'=>:ILIKE}
- # Standard Mathematical Operators used in NumericMethods
+ # Standard mathematical operators used in +NumericMethods+
MATHEMATICAL_OPERATORS = [:+, :-, :/, :*]
- # Bitwise Mathematical Operators used in NumericMethods
+ # Bitwise mathematical operators used in +NumericMethods+
BITWISE_OPERATORS = [:&, :|, :^, :<<, :>>]
- # Inequality Operators used in InequalityMethods
+ # Inequality operators used in +InequalityMethods+
INEQUALITY_OPERATORS = [:<, :>, :<=, :>=]
- # Hash of ruby operator symbols to SQL operators, used in BooleanMethods
+ # Hash of ruby operator symbols to SQL operators, used in +BooleanMethods+
BOOLEAN_OPERATOR_METHODS = {:& => :AND, :| =>:OR}
# Operators that use IN/NOT IN for inclusion/exclusion
@@ -146,7 +149,7 @@ class ComplexExpression < Expression
# Operator symbols that take one or more arguments
N_ARITY_OPERATORS = [:AND, :OR, :'||'] + MATHEMATICAL_OPERATORS
- # Operator symbols that take one argument
+ # Operator symbols that take only a single argument
ONE_ARITY_OPERATORS = [:NOT, :NOOP, :'B~']
# An array of args for this object
@@ -156,9 +159,10 @@ class ComplexExpression < Expression
attr_reader :op
# Set the operator symbol and arguments for this object to the ones given.
- # Convert all args that are hashes or arrays with all two pairs to BooleanExpressions.
- # Raise an error if the operator doesn't allow boolean input and a boolean argument is given.
- # Raise an error if the wrong number of arguments for a given operator is used.
+ # Convert all args that are hashes or arrays of two element arrays to +BooleanExpressions+,
+ # other than the second arg for an IN/NOT IN operator.
+ # Raise an +Error+ if the operator doesn't allow boolean input and a boolean argument is given.
+ # Raise an +Error+ if the wrong number of arguments for a given operator is used.
def initialize(op, *args)
orig_args = args
args = args.map{|a| Sequel.condition_specifier?(a) ? SQL::BooleanExpression.from_value_pairs(a) : a}
@@ -187,7 +191,7 @@ def initialize(op, *args)
end
# The base class for expressions that can be used in multiple places in
- # the SQL query.
+ # an SQL query.
class GenericExpression < Expression
end
@@ -195,15 +199,15 @@ class GenericExpression < Expression
# Methods that create aliased identifiers
module AliasMethods
- # Create an SQL column alias of the receiving column or expression to the given alias.
+ # Create an SQL column alias (+AliasedExpression+) of the receiving column or expression to the given alias.
def as(aliaz)
AliasedExpression.new(self, aliaz)
end
end
# This defines the bitwise methods: &, |, ^, ~, <<, and >>. Because these
- # methods overlap with the standard BooleanMethods methods, and they only
- # make sense for numbers, they are only included in NumericExpression.
+ # methods overlap with the standard +BooleanMethods methods+, and they only
+ # make sense for integers, they are only included in +NumericExpression+.
module BitwiseMethods
ComplexExpression::BITWISE_OPERATORS.each do |o|
define_method(o) do |ce|
Please sign in to comment.
Something went wrong with that request. Please try again.