sequel 3.12.1 → 3.13.0

data/lib/sequel/plugins/lazy_attributes.rb

@@ -70,7 +70,7 @@ module Sequel
         # the attribute for the current object.
         def lazy_attribute_lookup(a)
           primary_key = model.primary_key
-          model.select(*(Array(primary_key) + [a])).filter(primary_key=>::Sequel::SQL::SQLArray.new(retrieved_with.map{|o| o.pk})).all if model.identity_map && retrieved_with
+          model.select(*(Array(primary_key) + [a])).filter(primary_key=>retrieved_with.map{|o| o.pk}).all if model.identity_map && retrieved_with
           values[a] = this.select(a).first[a] unless values.include?(a)
           values[a]
         end

data/lib/sequel/plugins/list.rb

@@ -0,0 +1,174 @@
+module Sequel
+  module Plugins
+    # The list plugin allows for model instances to be part of an ordered list,
+    # based on a position field in the database.  It can either consider all
+    # rows in the table as being from the same list, or you can specify scopes
+    # so that multiple lists can be kept in the same table.
+    # 
+    # Basic Example:
+    #
+    #   class Item < Sequel::Model(:items)
+    #     plugin :list # will use :position field for position
+    #     plugin :list, :field=>:pos # will use :pos field for position
+    #   end
+    #   
+    #   item = Item[1]
+    # 
+    #   # Get the next or previous item in the list
+    # 
+    #   item.next
+    #   item.prev
+    # 
+    #   # Modify the item's position, which may require modifying other items in
+    #   # the same list
+    # 
+    #   item.move_to(3)
+    #   item.move_to_top
+    #   item.move_to_bottom
+    #   item.move_up
+    #   item.move_down
+    # 
+    # You can provide a <tt>:scope</tt> option to scope the list.  This option
+    # can be a symbol or array of symbols specifying column name(s), or a proc
+    # that accepts a model instance and returns a dataset representing the list
+    # the object is in.
+    # 
+    # For example, if each item has a +user_id+ field, and you want every user
+    # to have their own list:
+    #
+    #   Item.plugin :list, :scope=>:user_id
+    # 
+    # Note that using this plugin modifies the order of the model's dataset to
+    # sort by the position and scope fields.
+    #
+    # Also note that unlike ruby arrays, the list plugin assumes that the
+    # first entry in the list has position 1, not position 0.
+    #
+    # Copyright (c) 2007-2010 Sharon Rosner, Wayne E. Seguin, Aman Gupta, Adrian Madrid, Jeremy Evans
+    module List
+      # Set the +position_field+ and +scope_proc+ attributes for the model,
+      # using the <tt>:field</tt> and <tt>:scope</tt> options, respectively.
+      # The <tt>:scope</tt> option can be a symbol, array of symbols, or a proc that
+      # accepts a model instance and returns a dataset representing the list.
+      # Also, modify the model dataset's order to order by the position and scope fields.
+      def self.configure(model, opts = {})
+        model.position_field = opts[:field] || :position
+        model.dataset = model.dataset.order_prepend(model.position_field)
+        
+        model.scope_proc = case scope = opts[:scope]
+        when Symbol
+          model.dataset = model.dataset.order_prepend(scope)
+          proc{|obj| obj.model.filter(scope=>obj.send(scope))}
+        when Array
+          model.dataset = model.dataset.order_prepend(*scope)
+          proc{|obj| obj.model.filter(scope.map{|s| [s, obj.send(s)]})}
+        else
+          scope
+        end
+      end
+
+      module ClassMethods
+        # The column name holding the position in the list, as a symbol.
+        attr_accessor :position_field
+
+        # A proc that scopes the dataset, so that there can be multiple positions 
+        # in the list, but the positions are unique with the scoped dataset. This
+        # proc should accept an instance and return a dataset representing the list.
+        attr_accessor :scope_proc
+
+        # Copy the +position_field+ and +scope_proc+ to the subclass.
+        def inherited(subclass)
+          super
+          subclass.position_field = position_field
+          subclass.scope_proc = scope_proc
+        end
+      end
+
+      module InstanceMethods
+        # The model object at the given position in the list containing this instance.
+        def at_position(p)
+          list_dataset.first(position_field => p)
+        end
+
+        # Find the last position in the list containing this instance.
+        def last_position
+          list_dataset.max(position_field).to_i
+        end
+
+        # A dataset that represents the list containing this instance.
+        def list_dataset
+          model.scope_proc ? model.scope_proc.call(self) : model.dataset
+        end
+
+        # Move this instance down the given number of places in the list,
+        # or 1 place if no argument is specified.
+        def move_down(n = 1)
+          move_to(position_value + n)
+        end
+
+        # Move this instance to the given place in the list.  Raises an
+        # exception if target is less than 1 or greater than the last position in the list.
+        def move_to(target, lp = nil)
+          current = position_value
+          if target != current
+            checked_transaction do
+              ds = list_dataset
+              op, ds = if target < current
+                raise(Sequel::Error, "Moving too far up (target = #{target})") if target < 1
+                [:+, ds.filter(position_field=>target...current)]
+              else
+                lp ||= last_position
+                raise(Sequel::Error, "Moving too far down (target = #{target}, last_position = #{lp})") if target > lp
+                [:-, ds.filter(position_field=>(current + 1)..target)]
+              end
+              ds.update(position_field => Sequel::SQL::NumericExpression.new(op, position_field, 1))
+              update(position_field => target)
+            end
+          end
+          self
+        end
+
+        # Move this instance to the bottom (last position) of the list.
+        def move_to_bottom
+          lp = last_position 
+          move_to(lp, lp)
+        end
+
+        # Move this instance to the top (first position, position 1) of the list.
+        def move_to_top
+          move_to(1)
+        end
+
+        # Move this instance the given number of places up in the list, or 1 place
+        # if no argument is specified.
+        def move_up(n = 1)
+          move_to(position_value - n) 
+        end
+
+        # The model instance the given number of places below this model instance
+        # in the list, or 1 place below if no argument is given.
+        def next(n = 1)
+          n == 0 ? self : at_position(position_value + n)
+        end
+
+        # The value of the model's position field for this instance.
+        def position_value
+          send(position_field)
+        end
+
+        # The model instance the given number of places below this model instance
+        # in the list, or 1 place below if no argument is given.
+        def prev(n = 1)
+          self.next(n * -1)
+        end
+
+        private
+
+        # The model's position field, an instance method for ease of use.
+        def position_field
+          model.position_field
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/many_through_many.rb

@@ -1,6 +1,6 @@
 module Sequel
   module Plugins
-    # The many_through_many plugin allow you to create a association to multiple objects using multiple join tables.
+    # The many_through_many plugin allow you to create an association to multiple objects using multiple join tables.
     # For example, assume the following associations:
     #
     #    Artist.many_to_many :albums
@@ -185,7 +185,7 @@ module Sequel
             ds = opts.associated_class 
             opts.reverse_edges.each{|t| ds = ds.join(t[:table], Array(t[:left]).zip(Array(t[:right])), :table_alias=>t[:alias])}
             ft = opts[:final_reverse_edge]
-            conds = uses_lcks ? [[left_keys.map{|k| SQL::QualifiedIdentifier.new(ft[:table], k)}, SQL::SQLArray.new(h.keys)]] : [[left_key, h.keys]]
+            conds = uses_lcks ? [[left_keys.map{|k| SQL::QualifiedIdentifier.new(ft[:table], k)}, h.keys]] : [[left_key, h.keys]]
             ds = ds.join(ft[:table], Array(ft[:left]).zip(Array(ft[:right])) + conds, :table_alias=>ft[:alias])
             model.eager_loading_dataset(opts, ds, Array(opts.select), eo[:associations], eo).all do |assoc_record|
               hash_key = if uses_lcks

data/lib/sequel/plugins/rcte_tree.rb

@@ -95,19 +95,18 @@ module Sequel
       # Create the appropriate parent, children, ancestors, and descendants
       # associations for the model.
       def self.apply(model, opts={})
+        model.plugin :tree, opts
+
         opts = opts.dup
         opts[:class] = model
+        opts[:methods_module] = Module.new
+        model.send(:include, opts[:methods_module])
         
         key = opts[:key] ||= :parent_id
         prkey = opts[:primary_key] ||= model.primary_key
         
-        par = opts.merge(opts.fetch(:parent, {}))
-        parent = par.fetch(:name, :parent)
-        model.many_to_one parent, par
-        
-        chi = opts.merge(opts.fetch(:children, {}))
-        childrena = chi.fetch(:name, :children)
-        model.one_to_many childrena, chi
+        parent = opts.merge(opts.fetch(:parent, {})).fetch(:name, :parent)
+        childrena = opts.merge(opts.fetch(:children, {})).fetch(:name, :children)
         
         ka = opts[:key_alias] ||= :x_root_x
         t = opts[:cte_name] ||= :t

data/lib/sequel/plugins/tree.rb

@@ -0,0 +1,118 @@
+module Sequel
+  module Plugins
+    # The Tree plugin adds additional associations and methods that allow you to 
+    # treat a Model as a tree.  
+    #
+    # A column for holding the parent key is required and is :parent_id by default.  
+    # This may be overridden by passing column name via :key
+    #
+    # Optionally, a column to control order of nodes returned can be specified
+    # by passing column name via :order.
+    # 
+    # Examples:
+    #
+    #   class Node < Sequel::Model
+    #     plugin :tree
+    #   end
+    #  
+    #   class Node < Sequel::Model
+    #     plugin :tree, :key=>:parentid, :order=>:position
+    #   end
+    module Tree
+      # Create parent and children associations.  Any options
+      # specified are passed to both associations.  You can
+      # specify options to use for the parent association
+      # using a :parent option, and options to use for the
+      # children association using a :children option.
+      def self.apply(model, opts={})
+        opts = opts.dup
+        opts[:class] = model
+
+        model.instance_eval do
+          @parent_column = (opts[:key] ||= :parent_id)
+          @tree_order = opts[:order]
+        end
+        
+        par = opts.merge(opts.fetch(:parent, {}))
+        parent = par.fetch(:name, :parent)
+        model.many_to_one parent, par
+        
+        chi = opts.merge(opts.fetch(:children, {}))
+        children = chi.fetch(:name, :children)
+        model.one_to_many children, chi
+      end
+      
+      module ClassMethods
+        # The column symbol or array of column symbols on which to order the tree.
+        attr_accessor :tree_order
+        
+        # The symbol for the column containing the value pointing to the
+        # parent of the leaf.
+        attr_accessor :parent_column
+
+        # Copy the +parent_column+ and +order_column+ to the subclass.
+        def inherited(subclass)
+          super
+          subclass.parent_column = parent_column
+          subclass.tree_order = tree_order 
+        end
+
+        # Returns list of all root nodes (those with no parent nodes).
+        #
+        #   TreeClass.roots # => [root1, root2]
+        def roots
+          roots_dataset.all
+        end
+        
+        # Returns the dataset for retrieval of all root nodes
+        #
+        #   TreeClass.roots_dataset => Sequel#Dataset
+        def roots_dataset
+          ds = filter(parent_column => nil)
+          ds = ds.order(*tree_order) if tree_order
+          ds
+        end
+      end
+      
+      module InstanceMethods
+        # Returns list of ancestors, starting from parent until root.
+        #
+        #   subchild1.ancestors # => [child1, root]
+        def ancestors
+          node, nodes = self, []
+          nodes << node = node.parent while node.parent
+          nodes
+        end
+
+        # Returns list of ancestors, starting from parent until root.
+        #
+        #   subchild1.ancestors # => [child1, root]
+        def descendants
+          nodes = self.children.dup
+          nodes.each{|child| nodes.concat(child.descendants)}
+          nodes 
+        end
+
+        # Returns the root node of the tree that this node descends from
+        # This node is returned if it is a root node itself.
+        def root
+          ancestors.last || self
+        end
+
+        # Returns all siblings and a reference to the current node.
+        #
+        #   subchild1.self_and_siblings # => [subchild1, subchild2]
+        def self_and_siblings
+          parent ? parent.children : model.roots
+        end
+
+        # Returns all siblings of the current node.
+        #
+        #   subchild1.siblings # => [subchild2]
+        def siblings
+          self_and_siblings - [self]
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/xml_serializer.rb

@@ -0,0 +1,321 @@
+module Sequel
+  tsk_require 'nokogiri'
+
+  module Plugins
+    # The xml_serializer plugin handles serializing entire Sequel::Model
+    # objects to XML, and deserializing XML into a single Sequel::Model
+    # object or an array of Sequel::Model objects.  It requires the
+    # nokogiri library.
+    #
+    # Basic Example:
+    #
+    #   album = Album[1]
+    #   puts album.to_xml
+    #   # Output:
+    #   <?xml version="1.0"?>
+    #   <album>
+    #     <id>1</id>
+    #     <name>RF</name>
+    #     <artist_id>2</artist_id>
+    #   </album>
+    #
+    # You can provide options to control the XML output:
+    #
+    #   puts album.to_xml(:only=>:name)
+    #   puts album.to_xml(:except=>[:id, :artist_id])
+    #   # Output:
+    #   <?xml version="1.0"?>
+    #   <album>
+    #     <name>RF</name>
+    #   </album>
+    #
+    #   album.to_xml(:include=>:artist)
+    #   # Output:
+    #   <?xml version="1.0"?>
+    #   <album>
+    #     <id>1</id>
+    #     <name>RF</name>
+    #     <artist_id>2</artist_id>
+    #     <artist>
+    #       <id>2</id>
+    #       <name>YJM</name>
+    #     </artist>
+    #   </album>
+    # 
+    # You can use a hash value with <tt>:include</tt> to pass options
+    # to associations:
+    #
+    #   album.to_json(:include=>{:artist=>{:only=>:name}})
+    #   # Output:
+    #   <?xml version="1.0"?>
+    #   <album>
+    #     <id>1</id>
+    #     <name>RF</name>
+    #     <artist_id>2</artist_id>
+    #     <artist>
+    #       <name>YJM</name>
+    #     </artist>
+    #   </album>
+    #
+    # In addition to creating XML, this plugin also enables Sequel::Model
+    # objects to be created by parsing XML:
+    #
+    #   xml = album.to_xml
+    #   album = Album.from_xml(xml)
+    #
+    # In addition, you can update existing model objects directly from XML
+    # using +from_xml+:
+    #
+    #   album.from_xml(xml)
+    #
+    # Additionally, +to_xml+ also exists as a class and dataset method, both
+    # of which return all objects in the dataset:
+    #
+    #   Album.to_xml
+    #   Album.filter(:artist_id=>1).to_xml(:include=>:tags)
+    #
+    # Such XML can be loaded back into an array of Sequel::Model objects using
+    # +array_from_xml+:
+    #
+    #   Album.array_from_xml(Album.to_xml) # same as Album.all
+    #
+    # Usage:
+    #
+    #   # Add XML output capability to all model subclass instances (called before loading subclasses)
+    #   Sequel::Model.plugin :xml_serializer
+    #
+    #   # Add XML output capability to Album class instances
+    #   Album.plugin :xml_serializer
+    module XmlSerializer
+      module ClassMethods
+        # Proc that camelizes the input string, used for the :camelize option
+        CAMELIZE = proc{|s| s.camelize}
+
+        # Proc that dasherizes the input string, used for the :dasherize option
+        DASHERIZE = proc{|s| s.dasherize}
+
+        # Proc that returns the input string as is, used if
+        # no :name_proc, :dasherize, or :camelize option is used.
+        IDENTITY = proc{|s| s}
+
+        # Proc that underscores the input string, used for the :underscore option
+        UNDERSCORE = proc{|s| s.underscore}
+
+        # Return an array of instances of this class based on
+        # the provided XML.
+        def array_from_xml(xml, opts={})
+          Nokogiri::XML(xml).children.first.children.reject{|c| c.is_a?(Nokogiri::XML::Text)}.map{|c| from_xml_node(c, opts)}
+        end
+
+        # Return an instance of this class based on the provided
+        # XML.
+        def from_xml(xml, opts={})
+          from_xml_node(Nokogiri::XML(xml).children.first, opts)
+        end
+
+        # Return an instance of this class based on the given
+        # XML node, which should be Nokogiri::XML::Node instance.
+        # This should probably not be used directly by user code.
+        def from_xml_node(parent, opts={})
+          new.from_xml_node(parent, opts)
+        end
+
+        # Call the dataset +to_xml+ method.
+        def to_xml(opts={})
+          dataset.to_xml(opts)
+        end
+
+        # Return an appropriate Nokogiri::XML::Builder instance
+        # used to create the XML.  This should probably not be used
+        # directly by user code.
+        def xml_builder(opts={})
+          if opts[:builder]
+            opts[:builder]
+          else
+            builder_opts = if opts[:builder_opts]
+              opts[:builder_opts]
+            else
+              {}
+            end
+            builder_opts[:encoding] = opts[:encoding] if opts.has_key?(:encoding)
+            Nokogiri::XML::Builder.new(builder_opts)
+          end
+        end
+
+        # Return a proc (or any other object that responds to []),
+        # used for formatting XML tag names when serializing to XML.
+        # This should probably not be used directly by user code.
+        def xml_deserialize_name_proc(opts={})
+          if opts[:name_proc]
+            opts[:name_proc]
+          elsif opts[:underscore]
+            UNDERSCORE
+          else
+            IDENTITY
+          end
+        end
+
+        # Return a proc (or any other object that responds to []),
+        # used for formatting XML tag names when serializing to XML.
+        # This should probably not be used directly by user code.
+        def xml_serialize_name_proc(opts={})
+          pr = if opts[:name_proc]
+            opts[:name_proc]
+          elsif opts[:dasherize]
+            DASHERIZE
+          elsif opts[:camelize]
+            CAMELIZE
+          else
+            IDENTITY
+          end
+          proc{|s| "#{pr[s]}_"}
+        end
+      end
+
+      module InstanceMethods
+        # Update the contents of this instance based on the given XML.
+        # Accepts the following options:
+        #
+        # :name_proc :: Proc or Hash that accepts a string and returns
+        #               a string, used to convert tag names to column or
+        #               association names.
+        # :underscore :: Sets the :name_proc option to one that calls +underscore+
+        #                on the input string.  Requires that you load the inflector
+        #                extension or another library that adds String#underscore.
+        def from_xml(xml, opts={})
+          from_xml_node(Nokogiri::XML(xml).children.first, opts)
+        end
+
+        # Update the contents of this instance based on the given 
+        # XML node, which should be a Nokogiri::XML::Node instance.
+        def from_xml_node(parent, opts={})
+          cols = model.columns.map{|x| x.to_s}
+          assocs = {}
+          model.associations.map{|x| assocs[x.to_s] = model.association_reflection(x)}
+          meths = send(:setter_methods, nil, nil)
+          name_proc = model.xml_deserialize_name_proc(opts)
+          parent.children.each do |node|
+            next if node.is_a?(Nokogiri::XML::Text)
+            k = name_proc[node.name]
+            if ar = assocs[k]
+              klass = ar.associated_class
+              associations[k.to_sym] = if ar.returns_array?
+                node.children.reject{|c| c.is_a?(Nokogiri::XML::Text)}.map{|c| klass.from_xml_node(c)}
+              else
+                klass.from_xml_node(node)
+              end
+            elsif cols.include?(k)
+              self[k.to_sym] = node.children.first.to_s
+            elsif meths.include?("#{k}=")
+              send("#{k}=", node.children.first.to_s)
+            else
+              raise Error, "Entry in XML not an association or column and no setter method exists: #{k}"
+            end
+          end
+          self
+        end
+
+        # Return a string in XML format.  If a block is given, yields the XML
+        # builder object so you can add additional XML tags.
+        # Accepts the following options:
+        #
+        # :builder :: The builder instance used to build the XML,
+        #             which should be an instance of Nokogiri::XML::Node.  This
+        #             is necessary if you are serializing entire object graphs,
+        #             like associated objects.
+        # :builder_opts :: Options to pass to the Nokogiri::XML::Builder
+        #                  initializer, if the :builder option is not provided.
+        # :camelize:: Sets the :name_proc option to one that calls +camelize+
+        #             on the input string.  Requires that you load the inflector
+        #             extension or another library that adds String#camelize.
+        # :dasherize :: Sets the :name_proc option to one that calls +dasherize+
+        #               on the input string.  Requires that you load the inflector
+        #               extension or another library that adds String#dasherize.
+        # :encoding :: The encoding to use for the XML output, passed
+        #              to the Nokogiri::XML::Builder initializer.
+        # :except :: Symbol or Array of Symbols of columns not
+        #            to include in the XML output.
+        # :include :: Symbol, Array of Symbols, or a Hash with
+        #             Symbol keys and Hash values specifying
+        #             associations or other non-column attributes
+        #             to include in the XML output.  Using a nested
+        #             hash, you can pass options to associations
+        #             to affect the XML used for associated objects.
+        # :name_proc :: Proc or Hash that accepts a string and returns
+        #               a string, used to format tag names.
+        # :only :: Symbol or Array of Symbols of columns to only
+        #          include in the JSON output, ignoring all other
+        #          columns.
+        # :root_name :: The base name to use for the XML tag that
+        #               contains the data for this instance.  This will
+        #               be the name of the root node if you are only serializing
+        #               a single object, but not if you are serializing
+        #               an array of objects using Model.to_xml or Dataset#to_xml.
+        # :types :: Set to true to include type information for
+        #           all of the columns, pulled from the db_schema.
+        def to_xml(opts={})
+          vals = values
+          types = opts[:types]
+          inc = opts[:include]
+
+          cols = if only = opts[:only]
+            Array(only)
+          else
+            vals.keys - Array(opts[:except])
+          end
+
+          name_proc = model.xml_serialize_name_proc(opts)
+          x = model.xml_builder(opts)
+          x.send(name_proc[opts.fetch(:root_name, model.send(:underscore, model.name)).to_s]) do |x1|
+            cols.each do |c|
+              x1.send(name_proc[c.to_s], vals[c], types ? {:type=>db_schema.fetch(c, {})[:type]} : {})
+            end
+            if inc.is_a?(Hash)
+              inc.each{|k, v| to_xml_include(x1, k, v)}
+            else
+              Array(inc).each{|i| to_xml_include(x1, i)}
+            end
+            yield x1 if block_given?
+          end
+          x.to_xml
+        end
+
+        private
+
+        # Handle associated objects and virtual attributes when creating
+        # the xml.
+        def to_xml_include(node, i, opts={})
+          name_proc = model.xml_serialize_name_proc(opts)
+          objs = send(i)
+          if objs.is_a?(Array) && objs.all?{|x| x.is_a?(Sequel::Model)}
+            node.send(name_proc[i.to_s]) do |x2|
+              objs.each{|obj| obj.to_xml(opts.merge(:builder=>x2))}
+            end
+          elsif objs.is_a?(Sequel::Model)
+            objs.to_xml(opts.merge(:builder=>node, :root_name=>i))
+          else
+            node.send(name_proc[i.to_s], objs)
+          end
+        end
+      end
+
+      module DatasetMethods
+        # Return an XML string containing all model objects specified with
+        # this dataset.  Takes all of the options available to Model#to_xml,
+        # as well as the :array_root_name option for specifying the name of
+        # the root node that contains the nodes for all of the instances.
+        def to_xml(opts={})
+          raise(Sequel::Error, "Dataset#to_xml") unless row_proc
+          x = model.xml_builder(opts)
+          name_proc = model.xml_serialize_name_proc(opts)
+          x.send(name_proc[opts.fetch(:array_root_name, model.send(:pluralize, model.send(:underscore, model.name))).to_s]) do |x1|
+            all.each do |obj|
+              obj.to_xml(opts.merge(:builder=>x1))
+            end
+          end
+          x.to_xml
+        end
+      end
+    end
+  end
+end