sequel_core 1.4.0 → 1.5.0

data/lib/sequel_core/deprecated.rb

@@ -0,0 +1,200 @@
+module Sequel
+  # This module makes it easy to add deprecation functionality to other classes.
+  module Deprecation
+    # This sets the output stream for the deprecation messages.  Set it to an IO
+    # (or any object that responds to puts) and it will call puts on that
+    # object with the deprecation message.  Set to nil to ignore deprecation messages.
+    def self.deprecation_message_stream=(file)
+      @dms = file
+    end
+
+    # Set this to true to print tracebacks with every deprecation message,
+    # so you can see exactly where in your code the deprecated methods are
+    # being called.
+    def self.print_tracebacks=(pt)
+      @pt = pt
+    end
+
+    # Puts the messages unaltered to the deprecation message stream
+    def self.deprecate(message)
+      if @dms
+        @dms.puts(message)
+        caller.each{|c| @dms.puts(c)} if @pt 
+      end
+    end
+
+    # Formats the message with a message that it will be removed in Sequel 2.0.
+    # This is the method that is added to the classes that include Sequel::Deprecation.
+    def deprecate(meth, message = nil)
+      ::Sequel::Deprecation.deprecate("#{meth} is deprecated, and will be removed in Sequel 2.0.#{"  #{message}." if message}")
+    end
+  end
+  
+  class << self
+    include Sequel::Deprecation
+    def method_missing(m, *args) #:nodoc:
+      deprecate("Sequel.method_missing", "You should define Sequel.#{m} for the adapter.")
+      c = Database.adapter_class(m)
+      begin
+        # three ways to invoke this:
+        # 0 arguments: Sequel.dbi
+        # 1 argument:  Sequel.dbi(db_name)
+        # more args:   Sequel.dbi(db_name, opts)
+        case args.size
+        when 0
+          opts = {}
+        when 1
+          opts = args[0].is_a?(Hash) ? args[0] : {:database => args[0]}
+        else
+          opts = args[1].merge(:database => args[0])
+        end
+      rescue
+        raise Error::AdapterNotFound, "Unknown adapter (#{m})"
+      end
+      c.new(opts)
+    end
+  end
+
+  class Dataset
+    include Deprecation
+
+    MUTATION_RE = /^(.+)!$/.freeze
+
+    def clone_merge(opts = {}) #:nodoc:
+      deprecate("Sequel::Dataset#clone", "Use clone")
+      clone(opts)
+    end
+
+    def set_options(opts) #:nodoc:
+      deprecate("Sequel::Dataset#set_options")
+      @opts = opts
+      @columns = nil
+    end
+
+    def set_row_proc(&filter) #:nodoc:
+      deprecate("Sequel::Dataset#set_row_proc", "Use row_proc=")
+      @row_proc = filter
+    end
+
+    def remove_row_proc #:nodoc:
+      deprecate("Sequel::Dataset#remove_row_proc", "Use row_proc=nil")
+      @row_proc = nil
+    end
+
+    # Provides support for mutation methods (filter!, order!, etc.) and magic
+    # methods.
+    def method_missing(m, *args, &block) #:nodoc:
+      if m.to_s =~ MUTATION_RE
+        meth = $1.to_sym
+        super unless respond_to?(meth)
+        copy = send(meth, *args, &block)
+        super if copy.class != self.class
+        deprecate("Sequel::Dataset#method_missing", "Define Sequel::Dataset##{m}, or use Sequel::Dataset.def_mutation_method(:#{meth})")
+        @opts.merge!(copy.opts)
+        self
+      elsif magic_method_missing(m)
+        send(m, *args)
+      else
+         super
+      end
+    end
+
+    MAGIC_METHODS = {
+      /^order_by_(.+)$/   => proc {|c| proc {deprecate("Sequel::Dataset#method_missing", "Use order(#{c.inspect}) or define order_by_#{c}"); order(c)}},
+      /^first_by_(.+)$/   => proc {|c| proc {deprecate("Sequel::Dataset#method_missing", "Use order(#{c.inspect}).first or define first_by_#{c}"); order(c).first}},
+      /^last_by_(.+)$/    => proc {|c| proc {deprecate("Sequel::Dataset#method_missing", "Use order(#{c.inspect}).last or define last_by_#{c}"); order(c).last}},
+      /^filter_by_(.+)$/  => proc {|c| proc {|v| deprecate("Sequel::Dataset#method_missing", "Use filter(#{c.inspect}=>#{v.inspect}) or define filter_by_#{c}"); filter(c => v)}},
+      /^all_by_(.+)$/     => proc {|c| proc {|v| deprecate("Sequel::Dataset#method_missing", "Use filter(#{c.inspect}=>#{v.inspect}).all or define all_by_#{c}"); filter(c => v).all}},
+      /^find_by_(.+)$/    => proc {|c| proc {|v| deprecate("Sequel::Dataset#method_missing", "Use filter(#{c.inspect}=>#{v.inspect}).first or define find_by_#{c}"); filter(c => v).first}},
+      /^group_by_(.+)$/   => proc {|c| proc {deprecate("Sequel::Dataset#method_missing", "Use group(#{c.inspect}) or define group_by_#{c}"); group(c)}},
+      /^count_by_(.+)$/   => proc {|c| proc {deprecate("Sequel::Dataset#method_missing", "Use group_and_count(#{c.inspect}) or define count_by_#{c})"); group_and_count(c)}}
+    }
+
+    # Checks if the given method name represents a magic method and
+    # defines it. Otherwise, nil is returned.
+    def magic_method_missing(m) #:nodoc:
+      method_name = m.to_s
+      MAGIC_METHODS.each_pair do |r, p|
+        if method_name =~ r
+          impl = p[$1.to_sym]
+          return Dataset.class_def(m, &impl)
+        end
+      end
+      nil
+    end
+  end
+  
+  module SQL 
+    module DeprecatedColumnMethods #:nodoc:
+      AS = 'AS'.freeze
+      DESC = 'DESC'.freeze
+      ASC = 'ASC'.freeze
+
+      def as(a) #:nodoc:
+        Sequel::Deprecation.deprecate("Object#as is deprecated and will be removed in Sequel 2.0.  Use Symbol#as or String#as.")
+        ColumnExpr.new(self, AS, a)
+      end
+      def AS(a) #:nodoc:
+        Sequel::Deprecation.deprecate("Object#AS is deprecated and will be removed in Sequel 2.0.  Use Symbol#as or String#as.")
+        ColumnExpr.new(self, AS, a)
+      end
+      def desc #:nodoc:
+        Sequel::Deprecation.deprecate("Object#desc is deprecated and will be removed in Sequel 2.0.  Use Symbol#desc or String#desc.")
+        ColumnExpr.new(self, DESC)
+      end
+      def DESC #:nodoc:
+        Sequel::Deprecation.deprecate("Object#DESC is deprecated and will be removed in Sequel 2.0.  Use Symbol#desc or String#desc.")
+        ColumnExpr.new(self, DESC)
+      end
+      def asc #:nodoc:
+        Sequel::Deprecation.deprecate("Object#asc is deprecated and will be removed in Sequel 2.0.  Use Symbol#asc or String#asc.")
+        ColumnExpr.new(self, ASC)
+      end
+      def ASC #:nodoc:
+        Sequel::Deprecation.deprecate("Object#ASC is deprecated and will be removed in Sequel 2.0.  Use Symbol#asc or String#asc.")
+        ColumnExpr.new(self, ASC)
+      end
+      def all #:nodoc:
+        Sequel::Deprecation.deprecate("Object#all is deprecated and will be removed in Sequel 2.0.  Use :#{self}.* or '#{self}.*'.lit.")
+        Sequel::SQL::ColumnAll.new(self)
+      end
+      def ALL #:nodoc:
+        Sequel::Deprecation.deprecate("Object#ALL is deprecated and will be removed in Sequel 2.0.  Use :#{self}.* or '#{self}.*'.lit.")
+        Sequel::SQL::ColumnAll.new(self)
+      end
+
+      def cast_as(t) #:nodoc:
+        Sequel::Deprecation.deprecate("Object#cast_as is deprecated and will be removed in Sequel 2.0.  Use Symbol#cast_as or String#cast_as.")
+        if t.is_a?(Symbol)
+          t = t.to_s.lit
+        end
+        Sequel::SQL::Function.new(:cast, self.as(t))
+      end
+    end
+  end
+end
+
+class Object
+  include Sequel::SQL::DeprecatedColumnMethods
+  def Sequel(*args) #:nodoc:
+    Sequel::Deprecation.deprecate("Object#Sequel is deprecated and will be removed in Sequel 2.0.  Use Sequel.connect.")
+    Sequel.connect(*args)
+  end
+  def rollback! #:nodoc:
+    Sequel::Deprecation.deprecate("Object#rollback! is deprecated and will be removed in Sequel 2.0.  Use raise Sequel::Error::Rollback.")
+    raise Sequel::Error::Rollback
+  end
+end
+
+class Symbol
+  # Converts missing method calls into functions on columns, if the
+  # method name is made of all upper case letters.
+  def method_missing(sym, *args) #:nodoc:
+    if ((s = sym.to_s) =~ /^([A-Z]+)$/)
+      Sequel::Deprecation.deprecate("Symbol#method_missing is deprecated and will be removed in Sequel 2.0.  Use :#{sym}[:#{self}].")
+      Sequel::SQL::Function.new(s.downcase, self)
+    else
+      super
+    end
+  end
+end

data/lib/sequel_core/exceptions.rb

@@ -35,17 +35,3 @@ module Sequel
     class AdapterNotFound < Error ; end
   end  
 end
-
-# Object extensions
-class Object
-  # Cancels the current transaction without an error:
-  #
-  #   DB.tranaction do
-  #     ...
-  #     rollback! if failed_to_contact_client
-  #     ...
-  #   end
-  def rollback!
-    raise Sequel::Error::Rollback
-  end
-end

data/lib/sequel_core/object_graph.rb

@@ -0,0 +1,199 @@
+module Sequel
+  class Dataset
+    # Allows you to join multiple datasets/tables and have the result set
+    # split into component tables.
+    #
+    # This differs from the usual usage of join, which returns the result set
+    # as a single hash.  For example:
+    #
+    #   # CREATE TABLE artists (id INTEGER, name TEXT);
+    #   # CREATE TABLE albums (id INTEGER, name TEXT, artist_id INTEGER);
+    #   DB[:artists].left_outer_join(:albums, :artist_id=>:id).first
+    #   => {:id=>(albums.id||artists.id), :name=>(albums.name||artist.names), :artist_id=>albums.artist_id}
+    #   DB[:artists].graph(:albums, :artist_id=>:id).first
+    #   => {:artists=>{:id=>artists.id, :name=>artists.name}, :albums=>{:id=>albums.id, :name=>albums.name, :artist_id=>albums.artist_id}}
+    #
+    # Using a join such as left_outer_join, the attribute names that are shared between
+    # the tables are combined in the single return hash.  You can get around that by
+    # using .select with correct aliases for all of the columns, but it is simpler to
+    # use graph and have the result set split for you.  In addition, graph respects
+    # any row_proc or transform attributes of the current dataset and the datasets
+    # you use with graph.
+    #
+    # Arguments:
+    # * dataset -  Can be a symbol (specifying a table), another dataset,
+    #   or an object that responds to .dataset and yields a symbol or a dataset
+    # * join_conditions - A conditions hash that is passed to the join_table method
+    # * options -  A hash of graph options.  The following options are currently used:
+    #   * :table_alias - The alias to use for the table.  If not specified, doesn't
+    #     alias the table.  You will get an error if the the alias (or table) name is
+    #     used more than once.
+    #   * :join_type - The type of join to use (passed to join_table).  Defaults to
+    #     :left_outer.
+    #   * :select - Whether to select the columns from the you are joining, and 
+    #     include them as a separate hash in the output.  With this set to false,
+    #     it is like simply joining the tables.  This is designed to be used for
+    #     many_to_many join tables, where the columns are just foreign keys to primary
+    #     keys in other tables.
+    def graph(dataset, join_conditions, options = {})
+      # Allow the use of a model, dataset, or symbol as the first argument
+      # Find the table name/dataset based on the argument
+      dataset = dataset.dataset if dataset.respond_to?(:dataset)
+      case dataset
+      when Symbol
+        table = dataset
+        dataset = @db[dataset]
+      when ::Sequel::Dataset
+        table = dataset.first_source
+      else
+        raise Error, "The dataset argument should be a symbol, dataset, or model"
+      end
+
+      # Raise Sequel::Error with explanation that the table alias has been used
+      raise_alias_error = lambda do
+        raise(Error, "this #{options[:table_alias] ? 'alias' : 'table'} has already been been used, please specify " \
+          "#{options[:table_alias] ? 'a different alias' : 'an alias via the :table_alias option'}") 
+      end
+
+      # Only allow table aliases that haven't been used
+      table_alias = options[:table_alias] || table
+      raise_alias_error.call if @opts[:graph] && @opts[:graph][:table_aliases] && @opts[:graph][:table_aliases].include?(table_alias)
+
+      # Join the table early in order to avoid cloning the dataset twice
+      ds = join_table(options[:join_type] || :left_outer, table == table_alias ? table : "#{table} #{table_alias}", join_conditions)
+      opts = ds.opts
+
+      # Whether to include the table in the result set
+      add_table = options[:select] == false ? false : true
+      # Whether to add the columns to the list of column aliases
+      add_columns = !ds.opts.include?(:graph_aliases)
+
+      # Setup the initial graph data structure if it doesn't exist
+      unless graph = opts[:graph]
+        master = ds.first_source
+        raise_alias_error.call if master == table_alias
+        # Master hash storing all .graph related information
+        graph = opts[:graph] = {}
+        # Associates column aliases back to tables and columns
+        column_aliases = graph[:column_aliases] = {}
+        # Associates table alias (the master is never aliased)
+        table_aliases = graph[:table_aliases] = {master=>self}
+        # Keep track of the alias numbers used
+        ca_num = graph[:column_alias_num] = {}
+        # All columns in the master table are never
+        # aliased, but are not included if set_graph_aliases
+        # has been used.
+        if add_columns
+          select = (opts[:select] ||= [])
+          columns.each do |column|
+            column_aliases[column] = [master, column]
+            select.push(:"#{master}__#{column}")
+          end
+        end
+      end
+
+      # Add the table alias to the list of aliases
+      # Even if it isn't been used in the result set,
+      # we add a key for it with a nil value so we can check if it
+      # is used more than once
+      table_aliases = graph[:table_aliases]
+      table_aliases[table_alias] = add_table ? dataset : nil
+
+      # Add the columns to the selection unless we are ignoring them
+      if add_table && add_columns
+        select = opts[:select]
+        column_aliases = graph[:column_aliases]
+        ca_num = graph[:column_alias_num]
+        # If the column hasn't been used yet, don't alias it.
+        # If it has been used, try table_column.
+        # If that has been used, try table_column_N 
+        # using the next value of N that we know hasn't been
+        # used
+        dataset.columns.each do |column|
+          col_alias, c = if column_aliases[column]
+            tc = :"#{table_alias}_#{column}"
+            if column_aliases[tc]
+              if can = ca_num[tc]
+                ca_num[tc] += 1
+                tc = :"#{tc}_#{can}"
+              else
+                ca_num[tc] = 1
+                tc = :"#{tc}_0"
+             end
+            end
+            [tc, :"#{table_alias}__#{column}___#{tc}"]
+          else
+            [column, :"#{table_alias}__#{column}"]
+          end
+          column_aliases[col_alias] = [table_alias, column]
+          select.push(c)
+        end
+      end
+      ds
+    end
+
+    # This allows you to manually specify the graph aliases to use
+    # when using graph.  You can use it to only select certain
+    # columns, and have those columns mapped to specific aliases
+    # in the result set.  This is the equivalent of .select for a
+    # graphed dataset, and must be used instead of .select whenever
+    # graphing is used. Example:
+    #
+    #   DB[:artists].graph(:albums, :artist_id=>:id).set_graph_aliases(:artist_name=>[:artists, :name], :album_name=>[:albums, :name]).first
+    #   => {:artists=>{:name=>artists.name}, :albums=>{:name=>albums.name}}
+    #
+    # Arguments:
+    # * graph_aliases - Should be a hash with keys being symbols of
+    #   column aliases, and values being arrays with two symbol elements.
+    #   The first element of the array should be the table alias,
+    #   and the second should be the actual column name.
+    def set_graph_aliases(graph_aliases)
+      ds = select(*graph_aliases.collect{|col_alias, tc| :"#{tc[0]}__#{tc[1]}#{"___#{col_alias}" unless tc[1] == col_alias}"})
+      ds.opts[:graph_aliases]=graph_aliases
+      ds
+    end
+
+    private
+      # Fetch the rows, split them into component table parts,
+      # tranform and run the row_proc on each part (if applicable),
+      # and yield a hash of the parts.
+      def graph_each(opts, &block)
+        # Reject tables with nil datasets, as they are excluded from
+        # the result set
+        datasets = @opts[:graph][:table_aliases].to_a.reject{|ta,ds| ds.nil?}
+        # Get just the list of table aliases into a local variable, for speed
+        table_aliases = datasets.collect{|ta,ds| ta}
+        # Get an array of arrays, one for each dataset, with
+        # the necessary information about each dataset, for speed
+        datasets = datasets.collect do |ta, ds|
+          [ta, ds, ds.instance_variable_get(:@transform), ds.row_proc]
+        end
+        # Use the manually set graph aliases, if any, otherwise
+        # use the ones automatically created by .graph
+        column_aliases = @opts[:graph_aliases] || @opts[:graph][:column_aliases]
+        fetch_rows(select_sql(opts)) do |r|
+          graph = {}
+          # Create the sub hashes, one per table
+          table_aliases.each{|ta| graph[ta]={}}
+          # Split the result set based on the column aliases
+          # If there are columns in the result set that are
+          # not in column_aliases, they are ignored
+          column_aliases.each do |col_alias, tc|
+            ta, column = tc
+            graph[ta][column] = r[col_alias]
+          end
+          # For each dataset, transform and run the row
+          # row_proc if applicable
+          datasets.each do |ta,ds,tr,rp|
+            g = graph[ta]
+            g = ds.transform_load(g) if tr
+            g = rp[g] if rp
+            graph[ta] = g
+          end
+
+          yield graph
+        end
+        self
+      end
+  end
+end

data/lib/sequel_core/pretty_table.rb

@@ -1,13 +1,27 @@
 module Sequel
-  # Prints nice-looking plain-text tables
-  # +--+-------+
-  # |id|name   |
-  # |--+-------|
-  # |1 |fasdfas|
-  # |2 |test   |
-  # +--+-------+
   module PrettyTable
-    def self.records_columns(records)
+    # Prints nice-looking plain-text tables
+    # 
+    #   +--+-------+
+    #   |id|name   |
+    #   |--+-------|
+    #   |1 |fasdfas|
+    #   |2 |test   |
+    #   +--+-------+
+    def self.print(records, columns = nil) # records is an array of hashes
+      columns ||= records_columns(records)
+      sizes = column_sizes(records, columns)
+      
+      puts separator_line(columns, sizes)
+      puts header_line(columns, sizes)
+      puts separator_line(columns, sizes)
+      records.each {|r| puts data_line(columns, sizes, r)}
+      puts separator_line(columns, sizes)
+    end
+  end
+  class << PrettyTable
+    private
+    def records_columns(records)
       columns = []
       records.each do |r|
         if Array === r && (k = r.keys)
@@ -19,7 +33,7 @@ module Sequel
       columns
     end
     
-    def self.column_sizes(records, columns)
+    def column_sizes(records, columns)
       sizes = Hash.new {0}
       columns.each do |c|
         s = c.to_s.size
@@ -34,12 +48,12 @@ module Sequel
       sizes
     end
     
-    def self.separator_line(columns, sizes)
+    def separator_line(columns, sizes)
       l = ''
       '+' + columns.map {|c| '-' * sizes[c]}.join('+') + '+'
     end
     
-    def self.format_cell(size, v)
+    def format_cell(size, v)
       case v
       when Bignum, Fixnum
         "%#{size}d" % v
@@ -50,24 +64,13 @@ module Sequel
       end
     end
     
-    def self.data_line(columns, sizes, record)
+    def data_line(columns, sizes, record)
       '|' + columns.map {|c| format_cell(sizes[c], record[c])}.join('|') + '|'
     end
     
-    def self.header_line(columns, sizes)
+    def header_line(columns, sizes)
       '|' + columns.map {|c| "%-#{sizes[c]}s" % c.to_s}.join('|') + '|'
     end
-    
-    def self.print(records, columns = nil) # records is an array of hashes
-      columns ||= records_columns(records)
-      sizes = column_sizes(records, columns)
-      
-      puts separator_line(columns, sizes)
-      puts header_line(columns, sizes)
-      puts separator_line(columns, sizes)
-      records.each {|r| puts data_line(columns, sizes, r)}
-      puts separator_line(columns, sizes)
-    end
   end
 end