epugh-sequel 0.0.0

data/lib/sequel/model/plugins.rb

@@ -0,0 +1,74 @@
+module Sequel
+  # Empty namespace that plugins should use to store themselves,
+  # so they can be loaded via Model.plugin.
+  #
+  # Plugins should be modules with one of the following conditions:
+  # * A singleton method named apply, which takes a model and 
+  #   additional arguments.
+  # * A module inside the plugin module named InstanceMethods,
+  #   which will be included in the model class.
+  # * A module inside the plugin module named ClassMethods,
+  #   which will extend the model class.
+  # * A module inside the plugin module named DatasetMethods,
+  #   which will extend the model's dataset.
+  module Plugins
+  end
+  
+  class Model
+    # Loads a plugin for use with the model class, passing optional arguments
+    # to the plugin. If the plugin has a DatasetMethods module and the model
+    # doesn't have a dataset, raise an Error.
+    def self.plugin(plugin, *args)
+      arg = args.first
+      block = lambda{arg}
+      m = plugin.is_a?(Module) ? plugin : plugin_module(plugin)
+      if m.respond_to?(:apply)
+        m.apply(self, *args)
+      end
+      if m.const_defined?("InstanceMethods")
+        define_method(:"#{plugin}_opts", &block)
+        include(m::InstanceMethods)
+      end
+      if m.const_defined?("ClassMethods")
+        meta_def(:"#{plugin}_opts", &block)
+        extend(m::ClassMethods)
+      end
+      if m.const_defined?("DatasetMethods")
+        if @dataset
+          dataset.meta_def(:"#{plugin}_opts", &block)
+          dataset.extend(m::DatasetMethods)
+        end
+        dataset_method_modules << m::DatasetMethods
+        def_dataset_method(*m::DatasetMethods.public_instance_methods.reject{|x| DATASET_METHOD_RE !~ x.to_s})
+      end
+    end
+    
+    module ClassMethods
+      private
+  
+      # Returns the new style location for the plugin name.
+      def plugin_gem_location(plugin)
+        "sequel/plugins/#{plugin}"
+      end
+
+      # Returns the old style location for the plugin name.
+      def plugin_gem_location_old(plugin)
+        "sequel_#{plugin}"
+      end
+  
+      # Returns the module for the specified plugin. If the module is not 
+      # defined, the corresponding plugin gem is automatically loaded.
+      def plugin_module(plugin)
+        module_name = plugin.to_s.gsub(/(^|_)(.)/){|x| x[-1..-1].upcase}
+        if not Sequel::Plugins.const_defined?(module_name)
+          begin
+            require plugin_gem_location(plugin)
+          rescue LoadError
+            require plugin_gem_location_old(plugin)
+          end
+        end
+        Sequel::Plugins.const_get(module_name)
+      end
+    end
+  end
+end

data/lib/sequel/object_graph.rb

@@ -0,0 +1,230 @@
+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.
+    #
+    # If you are graphing a table and all columns for that table are nil, this
+    # indicates that no matching rows existed in the table, so graph will return nil
+    # instead of a hash with all nil values:
+    #
+    #   # If the artist doesn't have any albums
+    #   DB[:artists].graph(:albums, :artist_id=>:id).first
+    #   => {:artists=>{:id=>artists.id, :name=>artists.name}, :albums=>nil}
+    #
+    # 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 - Any condition(s) allowed by join_table.
+    # * options -  A hash of graph options.  The following options are currently used:
+    #   * :implicit_qualifier - The qualifier of implicit conditions, see #join_table.
+    #   * :join_type - The type of join to use (passed to join_table).  Defaults to
+    #     :left_outer.
+    #   * :select - An array of columns to select.  When not used, selects
+    #     all columns in the given dataset.  When set to false, selects no
+    #     columns and is like simply joining the tables, though graph keeps
+    #     some metadata about join that makes it important to use graph instead
+    #     of join.
+    #   * :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.
+    # * block - A block that is passed to join_table.
+    def graph(dataset, join_conditions = nil, options = {}, &block)
+      # 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, join_conditions, :table_alias=>table_alias, :implicit_qualifier=>options[:implicit_qualifier], &block)
+      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] = Hash.new(0)
+        # 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(column.qualify(master))
+          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]
+        # Which columns to add to the result set
+        cols = options[:select] || dataset.columns
+        # 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
+        cols.each do |column|
+          col_alias, identifier = if column_aliases[column]
+            column_alias = :"#{table_alias}_#{column}"
+            if column_aliases[column_alias]
+              column_alias_num = ca_num[column_alias]
+              column_alias = :"#{column_alias}_#{column_alias_num}" 
+              ca_num[column_alias] += 1
+            end
+            [column_alias, column.qualify(table_alias).as(column_alias)]
+          else
+            [column, column.qualify(table_alias)]
+          end
+          column_aliases[col_alias] = [table_alias, column]
+          select.push(identifier)
+        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_alias_columns(graph_aliases))
+      ds.opts[:graph_aliases] = graph_aliases
+      ds
+    end
+
+    # Adds the give graph aliases to the list of graph aliases to use,
+    # unlike #set_graph_aliases, which replaces the list.  See
+    # #set_graph_aliases.
+    def add_graph_aliases(graph_aliases)
+      ds = select_more(*graph_alias_columns(graph_aliases))
+      ds.opts[:graph_aliases] = (ds.opts[:graph_aliases] || {}).merge(graph_aliases)
+      ds
+    end
+
+    private
+
+    # Transform the hash of graph aliases to an array of columns
+    def graph_alias_columns(graph_aliases)
+      graph_aliases.collect do |col_alias, tc| 
+        identifier = tc[2] || tc[1].qualify(tc[0])
+        identifier = SQL::AliasedExpression.new(identifier, col_alias) if tc[2] or tc[1] != col_alias
+        identifier
+      end
+    end
+
+    # 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=(defarg=true;nil), &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(defarg ? select_sql : 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]
+          graph[ta] = if g.values.any?{|x| !x.nil?}
+            g = ds.transform_load(g) if tr
+            g = rp[g] if rp
+            g
+          else
+            nil
+          end
+        end
+
+        yield graph
+      end
+      self
+    end
+  end
+end

data/lib/sequel/plugins/caching.rb

@@ -0,0 +1,122 @@
+module Sequel
+  module Plugins
+    # Sequel's built-in caching plugin supports caching to any object that
+    # implements the Ruby-Memcache API.  You can add caching for any model
+    # or for all models via:
+    #
+    #   Model.plugin :caching, store   # Cache all models
+    #   MyModel.plugin :caching, store # Just cache MyModel
+    #
+    # The cache store should implement the Ruby-Memcache API:
+    #
+    #    cache_store.set(key, obj, time) # Associate the obj with the given key
+    #                                    # in the cache for the time (specified
+    #                                    # in seconds)
+    #    cache_store.get(key) => obj # Returns object set with same key
+    #    cache_store.get(key2) => nil # nil returned if there isn't an object
+    #                                 # currently in the cache with that key
+    module Caching
+      # Set the cache_store and cache_ttl attributes for the given model.
+      # If the :ttl option is not given, 3600 seconds is the default.
+      def self.apply(model, store, opts={})
+        model.instance_eval do
+          @cache_store = store
+          @cache_ttl = opts[:ttl] || 3600
+        end
+      end
+
+      module ClassMethods
+        # The cache store object for the model, which should implement the
+        # Ruby-Memcache API
+        attr_reader :cache_store
+        
+        # The time to live for the cache store, in seconds.
+        attr_reader :cache_ttl
+    
+        # Check the cache before a database lookup unless a hash is supplied.
+        def [](*args)
+          args = args.first if (args.size == 1)
+          return super(args) if args.is_a?(Hash)
+          ck = cache_key(args)
+          if obj = @cache_store.get(ck)
+            return obj
+          end
+          if obj = super(args)
+            @cache_store.set(ck, obj, @cache_ttl)
+          end 
+          obj
+        end
+
+        # Set the time to live for the cache store, in seconds (default is 3600, # so 1 hour).
+        def set_cache_ttl(ttl)
+          @cache_ttl = ttl
+        end
+        
+        # Copy the cache_store and cache_ttl to the subclass.
+        def inherited(subclass)
+          super
+          store = @cache_store
+          ttl = @cache_ttl
+          subclass.instance_eval do
+            @cache_store = store
+            @cache_ttl = ttl
+          end
+        end
+
+        private
+    
+        # Delete the entry with the matching key from the cache
+        def cache_delete(key)
+          @cache_store.delete(key)
+          nil
+        end
+    
+        # Return a key string for the pk
+        def cache_key(pk)
+          "#{self}:#{Array(pk).join(',')}"
+        end
+      end
+
+      module InstanceMethods
+        # Remove the object from the cache when updating
+        def before_update
+          return false if super == false
+          cache_delete
+        end
+
+        # Return a key unique to the underlying record for caching, based on the
+        # primary key value(s) for the object.  If the model does not have a primary
+        # key, raise an Error.
+        def cache_key
+          raise(Error, "No primary key is associated with this model") unless key = primary_key
+          pk = case key
+          when Array
+            key.collect{|k| @values[k]}
+          else
+            @values[key] || (raise Error, 'no primary key for this record')
+          end
+          model.send(:cache_key, pk)
+        end
+    
+        # Remove the object from the cache when deleting
+        def delete
+          cache_delete
+          super
+        end
+
+        # Remove the object from the cache when updating
+        def update_values(*args)
+          cache_delete
+          super
+        end
+
+        private
+    
+        # Delete this object from the cache
+        def cache_delete
+          model.send(:cache_delete, cache_key)
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/hook_class_methods.rb

@@ -0,0 +1,122 @@
+module Sequel
+  module Plugins
+    # Sequel's built-in hook class methods plugin is designed for backwards
+    # compatibility.  Its use is not encouraged, it is recommended to use
+    # instance methods and super instead of this plugin.  What this plugin
+    # allows you to do is, for example:
+    #
+    #   # Block only, can cause duplicate hooks if code is reloaded
+    #   before_save{self.created_at = Time.now}
+    #   # Block with tag, safe for reloading
+    #   before_save(:set_created_at){self.created_at = Time.now}
+    #   # Tag only, safe for reloading, calls instance method
+    #   before_save(:set_created_at)
+    #
+    # Pretty much anything you can do with a hook class method, you can also
+    # do with an instance method instead:
+    #
+    #    def before_save
+    #      return false if super == false
+    #      self.created_at = Time.now
+    #    end
+    module HookClassMethods
+      # Set up the hooks instance variable in the model.
+      def self.apply(model)
+        hooks = model.instance_variable_set(:@hooks, {})
+        Model::HOOKS.each{|h| hooks[h] = []}
+      end
+
+      module ClassMethods
+        Model::HOOKS.each{|h| class_eval("def #{h}(method = nil, &block); add_hook(:#{h}, method, &block) end", __FILE__, __LINE__)}
+
+        # This adds a new hook type. It will define both a class
+        # method that you can use to add hooks, as well as an instance method
+        # that you can use to call all hooks of that type.  The class method
+        # can be called with a symbol or a block or both.  If a block is given and
+        # and symbol is not, it adds the hook block to the hook type.  If a block
+        # and symbol are both given, it replaces the hook block associated with
+        # that symbol for a given hook type, or adds it if there is no hook block
+        # with that symbol for that hook type.  If no block is given, it assumes
+        # the symbol specifies an instance method to call and adds it to the hook
+        # type.
+        #
+        # If any hook block returns false, the instance method will return false
+        # immediately without running the rest of the hooks of that type.
+        #
+        # It is recommended that you always provide a symbol to this method,
+        # for descriptive purposes.  It's only necessary to do so when you 
+        # are using a system that reloads code.
+        # 
+        # Example of usage:
+        #
+        #  class MyModel
+        #   define_hook :before_move_to
+        #   before_move_to(:check_move_allowed){|o| o.allow_move?}
+        #   def move_to(there)
+        #     return if before_move_to == false
+        #     # move MyModel object to there
+        #   end
+        #  end
+        def add_hook_type(*hooks)
+          Model::HOOKS.concat(hooks)
+          hooks.each do |hook|
+            @hooks[hook] = []
+            instance_eval("def #{hook}(method = nil, &block); add_hook(:#{hook}, method, &block) end", __FILE__, __LINE__)
+            class_eval("def #{hook}; run_hooks(:#{hook}); end", __FILE__, __LINE__)
+          end
+        end
+    
+        # Returns true if there are any hook blocks for the given hook.
+        def has_hooks?(hook)
+          !@hooks[hook].empty?
+        end
+    
+        # Yield every block related to the given hook.
+        def hook_blocks(hook)
+          @hooks[hook].each{|k,v| yield v}
+        end
+
+        # Make a copy of the current class's hooks for the subclass.
+        def inherited(subclass)
+          super
+          hooks = subclass.instance_variable_set(:@hooks, {}) 
+          instance_variable_get(:@hooks).each{|k,v| hooks[k] = v.dup}
+        end
+    
+        private
+    
+        # Add a hook block to the list of hook methods.
+        # If a non-nil tag is given and it already is in the list of hooks,
+        # replace it with the new block.
+        def add_hook(hook, tag, &block)
+          unless block
+            (raise Error, 'No hook method specified') unless tag
+            block = proc {send tag}
+          end
+          h = @hooks[hook]
+          if tag && (old = h.find{|x| x[0] == tag})
+            old[1] = block
+          else
+            if hook.to_s =~ /^before/
+              h.unshift([tag,block])
+            else
+              h << [tag, block]
+            end
+          end
+        end
+      end
+
+      module InstanceMethods
+        Model::HOOKS.each{|h| class_eval("def #{h}; run_hooks(:#{h}); end", __FILE__, __LINE__)}
+
+        private
+
+        # Runs all hook blocks of given hook type on this object.
+        # Stops running hook blocks and returns false if any hook block returns false.
+        def run_hooks(hook)
+          model.hook_blocks(hook){|block| return false if instance_eval(&block) == false}
+        end
+      end
+    end
+  end
+end