sequel_core 1.5.1 → 2.0.0

data/lib/sequel_core/sql.rb

@@ -0,0 +1,394 @@
+# This file holds classes and modules under Sequel that are related to SQL
+# creation.
+
+module Sequel
+  # The SQL module holds classes whose instances represent SQL fragments.
+  # It also holds modules that are included in core ruby classes that
+  # make Sequel a friendly DSL.
+  module SQL
+    
+    ### Classes ###
+
+    # Base class for all SQL fragments
+    class Expression
+      # Returns self, because SQL::Expression already acts like
+      # LiteralString.
+      def lit
+        self
+      end
+    end
+    
+    # Represents all columns in a given table, table.* in SQL
+    class ColumnAll < Expression
+      # The table containing the columns being selected
+      attr_reader :table
+
+      # Create an object with the given table
+      def initialize(table)
+        @table = table
+      end
+
+      # ColumnAll expressions are considered equivalent if they
+      # have the same class and string representation
+      def ==(x)
+        x.class == self.class && @table == x.table
+      end
+
+      # Delegate the creation of the resulting SQL to the given dataset,
+      # since it may be database dependent.
+      def to_s(ds)
+        ds.column_all_sql(self)
+      end
+    end
+
+    # Represents a generic column expression, used for specifying order
+    # and aliasing of columns.
+    class ColumnExpr < Expression
+      # Created readers for the left, operator, and right expression.
+      attr_reader :l, :op, :r
+
+      # Sets the attributes for the object to those given.
+      # The right (r) is not required, it is used when aliasing.
+      # The left (l) usually specifies the column name, and the
+      # operator (op) is usually 'ASC', 'DESC', or 'AS'.
+      def initialize(l, op, r = nil)
+        @l, @op, @r = l, op, r
+      end
+      
+      # Delegate the creation of the resulting SQL to the given dataset,
+      # since it may be database dependent.
+      def to_s(ds)
+        ds.column_expr_sql(self)
+      end
+    end
+    
+    # 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.
+    #
+    # Most ruby operators methods are defined via metaprogramming: +, -, /, *, <, >, <=,
+    # >=, & (AND), | (OR). This allows for a simple DSL after some core
+    # classes have been overloaded with ComplexExpressionMethods.
+    class ComplexExpression < Expression
+      # A hash of the opposite for each operator symbol, used for inverting 
+      # objects.
+      OPERTATOR_INVERSIONS = {:AND => :OR, :OR => :AND, :< => :>=, :> => :<=,
+        :<= => :>, :>= => :<, :'=' => :'!=' , :'!=' => :'=', :LIKE => :'NOT LIKE',
+        :'NOT LIKE' => :LIKE, :~ => :'!~', :'!~' => :~, :IN => :'NOT IN',
+        :'NOT IN' => :IN, :IS => :'IS NOT', :'IS NOT' => :IS, :'~*' => :'!~*',
+        :'!~*' => :'~*'}
+
+      MATHEMATICAL_OPERATORS = [:+, :-, :/, :*]
+      INEQUALITY_OPERATORS = [:<, :>, :<=, :>=]
+      STRING_OPERATORS = [:'||']
+      SEARCH_OPERATORS = [:LIKE, :'NOT LIKE', :~, :'!~', :'~*', :'!~*']
+      INCLUSION_OPERATORS = [:IN, :'NOT IN']
+      BOOLEAN_OPERATORS = [:AND, :OR]
+
+      # Collection of all equality/inequality operator symbols
+      EQUALITY_OPERATORS = [:'=', :'!=', :IS, :'IS NOT', *INEQUALITY_OPERATORS]
+
+      # Operator symbols that do not work on boolean SQL input
+      NO_BOOLEAN_INPUT_OPERATORS = MATHEMATICAL_OPERATORS + INEQUALITY_OPERATORS + STRING_OPERATORS
+
+      # Operator symbols that result in boolean SQL output
+      BOOLEAN_RESULT_OPERATORS = BOOLEAN_OPERATORS + EQUALITY_OPERATORS + SEARCH_OPERATORS + INCLUSION_OPERATORS + [:NOT]
+
+      # Literal SQL booleans that are not allowed
+      BOOLEAN_LITERALS = [true, false, nil]
+
+      # Hash of ruby operator symbols to SQL operators, used for method creation
+      BOOLEAN_OPERATOR_METHODS = {:& => :AND, :| =>:OR}
+
+      # Operator symbols that take exactly two arguments
+      TWO_ARITY_OPERATORS = EQUALITY_OPERATORS + SEARCH_OPERATORS + INCLUSION_OPERATORS
+
+      # Operator symbols that take one or more arguments
+      N_ARITY_OPERATORS = MATHEMATICAL_OPERATORS + BOOLEAN_OPERATORS + STRING_OPERATORS
+
+      # An array of args for this object
+      attr_reader :args
+
+      # The operator symbol for this object
+      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 ComplexExpressions.
+      # 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)
+        args.collect! do |a|
+          case a
+          when Hash
+            a.sql_expr
+          when Array
+            a.all_two_pairs? ? a.sql_expr : a
+          else
+            a
+          end
+        end
+        if NO_BOOLEAN_INPUT_OPERATORS.include?(op)
+          args.each do |a|
+            if BOOLEAN_LITERALS.include?(a) || ((ComplexExpression === a) && BOOLEAN_RESULT_OPERATORS.include?(a.op))
+              raise(Sequel::Error, "cannot apply #{op} to a boolean expression")
+            end
+          end
+        end
+        case op
+        when *N_ARITY_OPERATORS
+          raise(Sequel::Error, 'mathematical and boolean operators require at least 1 argument') unless args.length >= 1
+        when *TWO_ARITY_OPERATORS
+          raise(Sequel::Error, '(in)equality operators require precisely 2 arguments') unless args.length == 2
+        when :NOT
+          raise(Sequel::Error, 'the NOT operator requires a single argument') unless args.length == 1
+        else
+          raise(Sequel::Error, "invalid operator #{op}")
+        end
+        @op = op
+        @args = args
+      end
+
+      # Take pairs of values (e.g. a hash or array of arrays of two pairs)
+      # and converts it to a ComplexExpression.  The operator and args
+      # used depends on the case of the right (2nd) argument:
+      # 
+      # * 0..10 - left >= 0 AND left <= 10
+      # * [1,2] - left IN (1,2)
+      # * nil - left IS NULL
+      # * /as/ - left ~ 'as'
+      # * :blah - left = blah
+      # * 'blah' - left = 'blah'
+      #
+      # If multiple arguments are given, they are joined with the op given (AND
+      # by default, OR possible).  If negate is set to true,
+      # all subexpressions are inverted before used.  Therefore, the following
+      # expressions are equivalent:
+      #
+      #   ~from_value_pairs(hash)
+      #   from_value_pairs(hash, :OR, true)
+      def self.from_value_pairs(pairs, op=:AND, negate=false)
+        pairs = pairs.collect do |l,r|
+          ce = case r
+          when Range
+            new(:AND, new(:>=, l, r.begin), new(r.exclude_end? ? :< : :<=, l, r.end))
+          when Array, ::Sequel::Dataset
+            new(:IN, l, r)
+          when NilClass
+            new(:IS, l, r)
+          when Regexp
+            like(l, r)
+          else
+            new(:'=', l, r)
+          end
+          negate ? ~ce : ce
+        end
+        pairs.length == 1 ? pairs.at(0) : new(op, *pairs)
+      end
+
+      # Creates a SQL pattern match exprssion. left (l) is the SQL string we
+      # are matching against, and ces are the patterns we are matching.
+      # The match succeeds if any of the patterns match (SQL OR).  Patterns
+      # can be given as strings or regular expressions.  Strings will cause
+      # the SQL LIKE operator to be used, and should be supported by most
+      # databases.  Regular expressions will probably only work on MySQL
+      # and PostgreSQL, and SQL regular expression syntax is not fully compatible
+      # with ruby regular expression syntax, so be careful if using regular 
+      # expressions.
+      def self.like(l, *ces)
+        ces.collect! do |ce| 
+          op, expr = Regexp === ce ? [ce.casefold? ? :'~*' : :~, ce.source] : [:LIKE, ce.to_s]
+          new(op, l, expr)
+        end
+        ces.length == 1 ? ces.at(0) : new(:OR, *ces)
+      end
+
+      # Invert the regular expression, if possible.  If the expression cannot
+      # be inverted, raise an error.  An inverted expression should match everything that the
+      # uninverted expression did not match, and vice-versa.
+      def ~
+        case @op
+        when *BOOLEAN_OPERATORS
+          self.class.new(OPERTATOR_INVERSIONS[@op], *@args.collect{|a| ComplexExpression === a ? ~a : ComplexExpression.new(:NOT, a)})
+        when *TWO_ARITY_OPERATORS
+          self.class.new(OPERTATOR_INVERSIONS[@op], *@args.dup)
+        when :NOT
+          @args.first
+        else
+          raise(Sequel::Error, "operator #{@op} cannot be inverted")
+        end
+      end
+
+      # Delegate the creation of the resulting SQL to the given dataset,
+      # since it may be database dependent.
+      def to_s(ds)
+        ds.complex_expression_sql(@op, @args)
+      end
+
+      BOOLEAN_OPERATOR_METHODS.each do |m, o|
+        define_method(m) do |ce|
+          raise(Sequel::Error, "cannot apply #{o} to a non-boolean expression") unless BOOLEAN_RESULT_OPERATORS.include?(@op)
+          super
+        end
+      end
+
+      (MATHEMATICAL_OPERATORS + INEQUALITY_OPERATORS).each do |o|
+        define_method(o) do |ce|
+          raise(Sequel::Error, "cannot apply #{o} to a boolean expression") unless NO_BOOLEAN_INPUT_OPERATORS.include?(@op)
+          super
+        end
+      end
+    end
+
+    # Represents an SQL function call.
+    class Function < Expression
+      # The array of arguments to pass to the function (may be blank)
+      attr_reader :args
+
+      # The SQL function to call
+      attr_reader :f
+      
+      # Set the attributes to the given arguments
+      def initialize(f, *args)
+        @f, @args = f, args
+      end
+
+      # Functions are considered equivalent if they
+      # have the same class, function, and arguments.
+      def ==(x)
+         x.class == self.class && @f == x.f && @args == x.args
+      end
+
+      # Delegate the creation of the resulting SQL to the given dataset,
+      # since it may be database dependent.
+      def to_s(ds)
+        ds.function_sql(self)
+      end
+    end
+    
+    # Represents a qualified (column with table) reference.  Used when
+    # joining tables to disambiguate columns.
+    class QualifiedColumnRef < Expression
+      # The table and column to reference
+      attr_reader :table, :column
+
+      # Set the attributes to the given arguments
+      def initialize(table, column)
+        @table, @column = table, column
+      end
+      
+      # Delegate the creation of the resulting SQL to the given dataset,
+      # since it may be database dependent.
+      def to_s(ds)
+        ds.qualified_column_ref_sql(self)
+      end 
+    end
+    
+    # Represents an SQL array access, with multiple possible arguments.
+    class Subscript < Expression
+      # The SQL array column
+      attr_reader :f
+
+      # The array of subscripts to use (should be an array of numbers)
+      attr_reader :sub
+
+      # Set the attributes to the given arguments
+      def initialize(f, sub)
+        @f, @sub = f, sub
+      end
+
+      # Create a new subscript appending the given subscript(s)
+      # the the current array of subscripts.
+      def |(sub)
+        Subscript.new(@f, @sub + Array(sub))
+      end
+      
+      # Delegate the creation of the resulting SQL to the given dataset,
+      # since it may be database dependent.
+      def to_s(ds)
+        ds.subscript_sql(self)
+      end
+    end
+
+    ### Modules ###
+    
+    # Module included in core classes giving them a simple and easy DSL
+    # for creation of ComplexExpressions.
+    #
+    # Most ruby operators methods are defined via metaprogramming: +, -, /, *, <, >, <=,
+    # >=, & (AND), | (OR). 
+    module ComplexExpressionMethods
+      NO_BOOLEAN_INPUT_OPERATORS = ComplexExpression::NO_BOOLEAN_INPUT_OPERATORS
+      BOOLEAN_RESULT_OPERATORS = ComplexExpression::BOOLEAN_RESULT_OPERATORS
+      BOOLEAN_OPERATOR_METHODS = ComplexExpression::BOOLEAN_OPERATOR_METHODS
+
+      BOOLEAN_OPERATOR_METHODS.each do |m, o|
+        define_method(m) do |ce|
+          raise(Sequel::Error, "cannot apply #{o} to a non-boolean expression") if (ComplexExpression === ce) && !BOOLEAN_RESULT_OPERATORS.include?(ce.op)
+          ComplexExpression.new(o, self, ce)   
+        end
+      end
+
+      (ComplexExpression::MATHEMATICAL_OPERATORS + ComplexExpression::INEQUALITY_OPERATORS).each do |o|
+        define_method(o) do |ce|
+          raise(Sequel::Error, "cannot apply #{o} to a boolean expression") if (ComplexExpression === ce) && !NO_BOOLEAN_INPUT_OPERATORS.include?(ce.op)
+          ComplexExpression.new(o, self, ce)   
+        end
+      end
+
+      # Create a new ComplexExpression with NOT, representing the inversion of whatever self represents.
+      def ~
+        ComplexExpression.new(:NOT, self)
+      end
+
+      # Create a ComplexExpression pattern match of self with the given patterns.
+      def like(*ces)
+        ComplexExpression.like(self, *ces)
+      end
+    end
+
+    # Holds methods that should be called on columns only.
+    module ColumnMethods
+      AS = 'AS'.freeze
+      DESC = 'DESC'.freeze
+      ASC = 'ASC'.freeze
+      
+      # Create an SQL column alias of the receiving column to the given alias.
+      def as(a)
+        ColumnExpr.new(self, AS, a)
+      end
+      
+      # Mark the receiving SQL column as sorting in a descending fashion.
+      def desc
+        ColumnExpr.new(self, DESC)
+      end
+      
+      # Mark the receiving SQL column as sorting in an ascending fashion (generally a no-op).
+      def asc
+        ColumnExpr.new(self, ASC)
+      end
+
+      # Cast the reciever to the given SQL type
+      def cast_as(t)
+        t = t.to_s.lit if t.is_a?(Symbol)
+        Sequel::SQL::Function.new(:cast, self.as(t))
+      end
+    end
+
+    class Expression
+      # Include the modules in Expression, couldn't be done
+      # earlier due to cyclic dependencies.
+      include ColumnMethods
+      include ComplexExpressionMethods
+    end
+  end
+
+  # LiteralString is used to represent literal SQL expressions. An 
+  # LiteralString is copied verbatim into an SQL statement. Instances of
+  # LiteralString can be created by calling String#lit.
+  # LiteralStrings can use all of the SQL::ColumnMethods and the 
+  # SQL::ComplexExpressionMethods.
+  class LiteralString < ::String
+    include SQL::ComplexExpressionMethods
+  end
+end

data/lib/sequel_core/worker.rb

@@ -1,12 +1,14 @@
-require "thread"
-
 module Sequel
-
+  # A Worker is a thread that accepts jobs off a work queue and
+  # processes them in the background.  It accepts an optional
+  # database where it wruns all of its work inside a transaction.
   class Worker < Thread
-      
     attr_reader :queue
     attr_reader :errors
   
+    # Setup the interal variables.  If a database is given,
+    # run the thread inside a database transaction. Continue
+    # to work until #join is called.
     def initialize(db = nil)
       @queue = Queue.new
       @errors = []
@@ -16,17 +18,8 @@ module Sequel
       db ? super {db.transaction {t.work}} : super {t.work}
     end
     
-    def work
-      loop {next_job}
-    rescue Sequel::Error::WorkerStop # signals the worker thread to stop
-    ensure
-      raise Sequel::Error::Rollback if @transaction && !@errors.empty?
-    end
-    
-    def busy?
-      @cur || !@queue.empty?
-    end
-  
+    # Add a job to the queue, specified either as a proc argument
+    # or as a block.
     def async(proc = nil, &block)
       @queue << (proc || block)
       self
@@ -34,25 +27,42 @@ module Sequel
     alias_method :add, :async
     alias_method :<<, :async
   
+    # Whether the worker is actively working and/or has work scheduled
+    def busy?
+      @cur || !@queue.empty?
+    end
+  
+    # Wait until the worker is no longer busy and then stop working.
     def join
-      while busy?
-        sleep 0.1
-      end
+      sleep(0.1) while busy?
       self.raise Error::WorkerStop
       super
     end
 
+    # Continually get jobs from the work queue and process them.
+    def work
+      begin
+        loop {next_job}
+      rescue Sequel::Error::WorkerStop # signals the worker thread to stop
+      ensure
+        raise Sequel::Error::Rollback if @transaction && !@errors.empty?
+      end
+    end
+    
     private
+
+    # Get the next job from the work queue and process it.
     def next_job
-      @cur = @queue.pop
-      @cur.call
-    rescue Error::WorkerStop => e
-      raise e
-    rescue Exception => e
-      @errors << e
-    ensure
-      @cur = nil
+      begin
+        @cur = @queue.pop
+        @cur.call
+      rescue Error::WorkerStop => e
+        raise e
+      rescue Exception => e
+        @errors << e
+      ensure
+        @cur = nil
+      end
     end
   end
-
 end

data/lib/sequel_core.rb

@@ -1,52 +1,106 @@
-require "metaid"
-require "bigdecimal"
-require "bigdecimal/util"
+%w'bigdecimal bigdecimal/util date enumerator thread time uri yaml'.each do |f|
+  require f
+end
+%w"core_ext sql core_sql connection_pool exceptions pretty_table
+  dataset migration schema database worker object_graph".each do |f|
+  require "sequel_core/#{f}"
+end
 
-files = %w[
-  deprecated core_ext core_sql connection_pool exceptions pretty_table
-  dataset migration schema database worker object_graph
-]
-dir = File.join(File.dirname(__FILE__), "sequel_core")
-files.each {|f| require(File.join(dir, f))}
+# Top level module for Sequel
+#
+# There are some class methods that are added via metaprogramming, one for
+# each supported adapter.  For example:
+#
+#   DB = Sequel.sqlite # Memory database
+#   DB = Sequel.sqlite('blog.db')
+#   DB = Sequel.postgres('database_name', :user=>'user', \
+#          :password=>'password', :host=>'host', :port=>5432, \
+#          :max_connections=>10)
+#
+# If a block is given to these meethods, it is passed the opened Database
+# object, which is closed when the block exits.  For example:
+#
+#   Sequel.sqlite('blog.db'){|db| puts db.users.count}  
+module Sequel
+  # Creates a new database object based on the supplied connection string
+  # and optional arguments.  The specified scheme determines the database
+  # class used, and the rest of the string specifies the connection options.
+  # For example:
+  #
+  #   DB = Sequel.connect('sqlite:/') # Memory database
+  #   DB = Sequel.connect('sqlite://blog.db') # ./blog.db
+  #   DB = Sequel.connect('sqlite:///blog.db') # /blog.db
+  #   DB = Sequel.connect('postgres://user:password@host:port/database_name')
+  #   DB = Sequel.connect('sqlite:///blog.db', :max_connections=>10)
+  #
+  # If a block is given, it is passed the opened Database object, which is
+  # closed when the block exits.  For example:
+  #
+  #   Sequel.connect('sqlite://blog.db'){|db| puts db.users.count}  
+  def self.connect(*args, &block)
+    Database.connect(*args, &block)
+  end
+  metaalias :open, :connect
+  
+  # Set whether to quote identifiers for all databases by default. By default,
+  # Sequel quotes identifiers in all SQL strings, so to turn that off:
+  #
+  #   Sequel.quote_identifiers = false
+  def self.quote_identifiers=(value)
+    Database.quote_identifiers = value
+  end
+  
+  # Set whether to set the single threaded mode for all databases by default. By default,
+  # Sequel uses a threadsafe connection pool, which isn't as fast as the
+  # single threaded connection pool.  If your program will only have one thread,
+  # and speed is a priority, you may want to set this to true:
+  #
+  #   Sequel.single_threaded = true
+  #
+  # Note that some database adapters (e.g. MySQL) have issues with single threaded mode if
+  # you try to perform more than one query simultaneously.  For example, the
+  # following code will not work well in single threaded mode on MySQL:
+  #
+  #   DB[:items].each{|i| DB[:nodes].filter(:item_id=>i[:id]).each{|n| puts "#{i} #{n}"}}
+  #
+  # Basically, you can't issue another query inside a call to Dataset#each in single
+  # threaded mode.  There is a fairly easy fix, just use Dataset#all inside
+  # Dataset#each for the outer query:
+  #
+  #   DB[:items].all{|i| DB[:nodes].filter(:item_id=>i[:id]).each{|n| puts "#{i} #{n}"}}
+  #
+  # Dataset#all gets all of the returned objects before calling the block, so the query
+  # isn't left open. Some of the adapters do this internally, and thus don't have a
+  # problem issuing queries inside of Dataset#each.
+  def self.single_threaded=(value)
+    Database.single_threaded = value
+  end
+  
+  ### Private Class Methods ###
 
-module Sequel #:nodoc:
-  Deprecation.deprecation_message_stream = STDERR
-  #Deprecation.print_tracebacks = true
-  class << self
-    # call-seq:
-    #   Sequel::Database.connect(conn_string)
-    #   Sequel.connect(conn_string)
-    #   Sequel.open(conn_string)
-    #
-    # Creates a new database object based on the supplied connection string.
-    # The specified scheme determines the database class used, and the rest
-    # of the string specifies the connection options. For example:
-    #   DB = Sequel.open 'sqlite:///blog.db'
-    def connect(*args)
-      Database.connect(*args)
-    end
-    alias_method :open, :connect
-    
-    def single_threaded=(value)
-      Database.single_threaded = value
+  # Helper method that the database adapter class methods that are added to Sequel via
+  # metaprogramming use to parse arguments.
+  def self.adapter_method(adapter, *args, &block) # :nodoc:
+    raise(::Sequel::Error, "Wrong number of arguments, 0-2 arguments valid") if args.length > 2
+    opts = {:adapter=>adapter.to_sym}
+    opts[:database] = args.shift if args.length >= 1 && !(args[0].is_a?(Hash))
+    if Hash === (arg = args[0])
+      opts.merge!(arg)
+    elsif !arg.nil?
+      raise ::Sequel::Error, "Wrong format of arguments, either use (), (String), (Hash), or (String, Hash)"
     end
+    connect(opts, &block)
+  end
 
-    def self.def_adapter_method(*adapters)
-      adapters.each do |adapter|
-        define_method(adapter) do |*args|
-          raise(::Sequel::Error, "Wrong number of arguments, 0-2 arguments valid") if args.length > 2
-          opts = {:adapter=>adapter.to_sym}
-          opts[:database] = args.shift if args.length >= 1 && !(args[0].is_a?(Hash))
-          if Hash === (arg = args[0])
-            opts.merge!(arg)
-          elsif !arg.nil?
-            raise ::Sequel::Error, "Wrong format of arguments, either use (), (String), (Hash), or (String, Hash)"
-          end
-          ::Sequel::Database.connect(opts)
-        end
-      end
+  # Method that adds a database adapter class method to Sequel that calls
+  # Sequel.adapter_method.
+  def self.def_adapter_method(*adapters) # :nodoc:
+    adapters.each do |adapter|
+      instance_eval("def #{adapter}(*args, &block); adapter_method('#{adapter}', *args, &block) end")
     end
-
-    def_adapter_method(*Database::ADAPTERS)
   end
+  metaprivate :adapter_method, :def_adapter_method
+  
+  # Add the database adapter class methods to Sequel via metaprogramming
+  def_adapter_method(*Database::ADAPTERS)
 end

data/spec/adapters/informix_spec.rb

@@ -1,4 +1,3 @@
-require File.join(File.dirname(__FILE__), '../../lib/sequel_core')
 require File.join(File.dirname(__FILE__), '../spec_helper.rb')
 
 unless defined?(INFORMIX_DB)