Permalink
Browse files

Minor RDoc updates to core_sql.rb

  • Loading branch information...
1 parent d7e89e3 commit e5a21f2e65ff0068e1b99683caeeada639de5957 @jeremyevans committed Jun 24, 2010
Showing with 34 additions and 29 deletions.
  1. +34 −29 lib/sequel/core_sql.rb
@@ -33,9 +33,9 @@ def case(default, expression = nil)
::Sequel::SQL::CaseExpression.new(self, default, expression)
end
- # Return a Sequel::SQL::ValueList created from this array. Used if this array contains
+ # Return a <tt>Sequel::SQL::ValueList</tt> created from this array. Used if this array contains
# all two element arrays and you want it treated as an SQL value list (IN predicate)
- # instead of a ordered hash-like conditions. This is not necessary if you are using
+ # instead of as a conditions specifier (similar to a hash). This is not necessary if you are using
# this array as a value in a filter, but may be necessary if you are using it as a
# value with placeholder SQL:
#
@@ -45,19 +45,24 @@ def case(default, expression = nil)
def sql_value_list
::Sequel::SQL::ValueList.new(self)
end
+
+ # Deprecated alias for sql_value_list
alias sql_array sql_value_list
- # Return a Sequel::SQL::BooleanExpression created from this array, matching all of the
+ # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this array, matching all of the
# conditions. Rarely do you need to call this explicitly, as Sequel generally
- # assumes that arrays of all two pairs specify this type of condition.
+ # assumes that arrays of two element arrays specify this type of condition. One case where
+ # it can be necessary to use this is if you are using the object as a value in a filter hash
+ # and want to use the = operator instead of the IN operator (which is used by default for
+ # arrays of two element arrays).
#
# [[:a, true]].sql_expr # SQL: a IS TRUE
# [[:a, 1], [:b, [2, 3]]].sql_expr # SQL: a = 1 AND b IN (2, 3)
def sql_expr
sql_expr_if_all_two_pairs
end
- # Return a Sequel::SQL::BooleanExpression created from this array, matching none
+ # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this array, matching none
# of the conditions.
#
# [[:a, true]].sql_negate # SQL: a IS NOT TRUE
@@ -66,7 +71,7 @@ def sql_negate
sql_expr_if_all_two_pairs(:AND, true)
end
- # Return a Sequel::SQL::BooleanExpression created from this array, matching any of the
+ # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this array, matching any of the
# conditions.
#
# [[:a, true]].sql_or # SQL: a IS TRUE
@@ -75,10 +80,10 @@ def sql_or
sql_expr_if_all_two_pairs(:OR)
end
- # Return a Sequel::SQL::BooleanExpression representing an SQL string made up of the
+ # Return a <tt>Sequel::SQL::BooleanExpression</tt> representing an SQL string made up of the
# concatenation of this array's elements. If an argument is passed
# it is used in between each element of the array in the SQL
- # concatenation. This does not require that the array be made up of all two pairs.
+ # concatenation.
#
# [:a].sql_string_join # SQL: a
# [:a, :b].sql_string_join # SQL: a || b
@@ -97,16 +102,16 @@ def sql_string_join(joiner=nil)
private
- # Raise an error if this array is not made up of all two pairs, otherwise create a Sequel::SQL::BooleanExpression from this array.
+ # Raise an error if this array is not made up all two element arrays, otherwise create a <tt>Sequel::SQL::BooleanExpression</tt> from this array.
def sql_expr_if_all_two_pairs(*args)
raise(Sequel::Error, 'Not all elements of the array are arrays of size 2, so it cannot be converted to an SQL expression') unless all_two_pairs?
::Sequel::SQL::BooleanExpression.from_value_pairs(self, *args)
end
end
-# Sequel extends the Hash class to add methods to implement the SQL DSL.
+# Sequel extends +Hash+ to add methods to implement the SQL DSL.
class Hash
- # Return a Sequel::SQL::BooleanExpression created from this hash, matching
+ # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this hash, matching
# all of the conditions in this hash and the condition specified by
# the given argument.
#
@@ -116,7 +121,7 @@ def &(ce)
::Sequel::SQL::BooleanExpression.new(:AND, self, ce)
end
- # Return a Sequel::SQL::BooleanExpression created from this hash, matching
+ # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this hash, matching
# all of the conditions in this hash or the condition specified by
# the given argument.
#
@@ -126,7 +131,7 @@ def |(ce)
::Sequel::SQL::BooleanExpression.new(:OR, self, ce)
end
- # Return a Sequel::SQL::BooleanExpression created from this hash, not matching all of the
+ # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this hash, not matching all of the
# conditions.
#
# ~{:a=>true} # SQL: a IS NOT TRUE
@@ -135,18 +140,18 @@ def ~
::Sequel::SQL::BooleanExpression.from_value_pairs(self, :OR, true)
end
- # Return a Sequel::SQL::CaseExpression with this hash as the conditions and the given
- # default value. Note that the order of the conditions will be arbitrary, so all
+ # Return a <tt>Sequel::SQL::CaseExpression</tt> with this hash as the conditions and the given
+ # default value. Note that the order of the conditions will be arbitrary on ruby 1.8, so all
# conditions should be orthogonal.
#
# {{:a=>[2,3]}=>1}.case(0) # SQL: CASE WHEN a IN (2, 3) THEN 1 ELSE 0 END
- # {:a=>1, {:b=>2}].case(:d, :c) # SQL: CASE c WHEN a THEN 1 WHEN b THEN 2 ELSE d END
+ # {:a=>1, :b=>2}.case(:d, :c) # SQL: CASE c WHEN a THEN 1 WHEN b THEN 2 ELSE d END
# # or: CASE c WHEN b THEN 2 WHEN a THEN 1 ELSE d END
def case(default, expression = nil)
::Sequel::SQL::CaseExpression.new(to_a, default, expression)
end
- # Return a Sequel::SQL::BooleanExpression created from this hash, matching all of the
+ # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this hash, matching all of the
# conditions. Rarely do you need to call this explicitly, as Sequel generally
# assumes that hashes specify this type of condition.
#
@@ -156,7 +161,7 @@ def sql_expr
::Sequel::SQL::BooleanExpression.from_value_pairs(self)
end
- # Return a Sequel::SQL::BooleanExpression created from this hash, matching none
+ # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this hash, matching none
# of the conditions.
#
# {:a=>true}.sql_negate # SQL: a IS NOT TRUE
@@ -165,7 +170,7 @@ def sql_negate
::Sequel::SQL::BooleanExpression.from_value_pairs(self, :AND, true)
end
- # Return a Sequel::SQL::BooleanExpression created from this hash, matching any of the
+ # Return a <tt>Sequel::SQL::BooleanExpression</tt> created from this hash, matching any of the
# conditions.
#
# {:a=>true}.sql_or # SQL: a IS TRUE
@@ -175,12 +180,12 @@ def sql_or
end
end
-# Sequel extends the String class to add methods to implement the SQL DSL.
+# Sequel extends +String+ to add methods to implement the SQL DSL.
class String
include Sequel::SQL::AliasMethods
include Sequel::SQL::CastMethods
- # Converts a string into a Sequel::LiteralString, in order to override string
+ # Converts a string into a <tt>Sequel::LiteralString</tt>, in order to override string
# literalization, e.g.:
#
# DB[:items].filter(:abc => 'def').sql #=>
@@ -189,22 +194,22 @@ class String
# DB[:items].filter(:abc => 'def'.lit).sql #=>
# "SELECT * FROM items WHERE (abc = def)"
#
- # You can also provide arguments, to create a Sequel::SQL::PlaceholderLiteralString:
+ # You can also provide arguments, to create a <tt>Sequel::SQL::PlaceholderLiteralString</tt>:
#
# DB[:items].select{|o| o.count('DISTINCT ?'.lit(:a))}.sql #=>
# "SELECT count(DISTINCT a) FROM items"
def lit(*args)
args.empty? ? Sequel::LiteralString.new(self) : Sequel::SQL::PlaceholderLiteralString.new(self, args)
end
- # Returns a Sequel::SQL::Blob that holds the same data as this string. Blobs provide proper
+ # Returns a <tt>Sequel::SQL::Blob</tt> that holds the same data as this string. Blobs provide proper
# escaping of binary data.
def to_sequel_blob
::Sequel::SQL::Blob.new(self)
end
end
-# Sequel extends the Symbol class to add methods to implement the SQL DSL.
+# Sequel extends +Symbol+ to add methods to implement the SQL DSL.
class Symbol
include Sequel::SQL::QualifyingMethods
include Sequel::SQL::IdentifierMethods
@@ -218,9 +223,9 @@ class Symbol
include Sequel::SQL::ComplexExpressionMethods
include Sequel::SQL::InequalityMethods if RUBY_VERSION < '1.9.0'
- # If no argument is given, returns a Sequel::SQL::ColumnAll object specifying all
+ # If no argument is given, returns a <tt>Sequel::SQL::ColumnAll</tt> object specifying all
# columns for this table.
- # If an argument is given, returns a Sequel::SQL::NumericExpression using the *
+ # If an argument is given, returns a <tt>Sequel::SQL::NumericExpression</tt> using the *
# (multiplication) operator with this and the given argument.
#
# :table.* # SQL: table.*
@@ -230,9 +235,9 @@ def *(ce=(arg=false;nil))
Sequel::SQL::ColumnAll.new(self);
end
- # Returns a Sequel::SQL::Function with this as the function name,
- # and the given arguments. This is aliased as Symbol#[] if the RUBY_VERSION
- # is less than 1.9.0. Ruby 1.9 defines Symbol#[], and Sequel
+ # Returns a <tt>Sequel::SQL::Function</tt> with this as the function name,
+ # and the given arguments. This is aliased as <tt>Symbol#[]</tt> if the RUBY_VERSION
+ # is less than 1.9.0. Ruby 1.9 defines <tt>Symbol#[]</tt>, and Sequel
# doesn't override methods defined by ruby itself.
#
# :now.sql_function # SQL: now()

0 comments on commit e5a21f2

Please sign in to comment.