sequel 3.21.0 → 3.41.0

data/lib/sequel/extensions/pg_hstore.rb

@@ -0,0 +1,334 @@
+# The pg_hstore extension adds support for the PostgreSQL hstore type
+# to Sequel.  hstore is an extension that ships with PostgreSQL, and
+# the hstore type stores an arbitrary key-value table, where the keys
+# are strings and the values are strings or NULL.
+#
+# This extension integrates with Sequel's native postgres adapter, so
+# that when hstore fields are retrieved, they are parsed and returned
+# as instances of Sequel::Postgres::HStore.  HStore is
+# a DelegateClass of Hash, so it mostly acts like a hash, but not
+# completely (is_a?(Hash) is false).  If you want the actual hash,
+# you can call Hstore#to_hash.  This is done so that Sequel does not
+# treat a HStore like a Hash by default, which would cause issues.
+#
+# In addition to the parsers, this extension comes with literalizers
+# for HStore using the standard Sequel literalization callbacks, so
+# they work with on all adapters.
+#
+# To turn an existing Hash into an HStore, use Sequel.hstore:
+#
+#   Sequel.hstore(hash)
+#
+# If you have loaded the {core_extensions extension}[link:files/doc/core_extensions_rdoc.html]),
+# you can also use Hash#hstore:
+# 
+#   hash.hstore
+#
+# Since the hstore type only supports strings, non string keys and
+# values are converted to strings
+#
+#   {:foo=>1}.hstore.to_hash # {'foo'=>'1'}
+#   v = {}.hstore
+#   v[:foo] = 1
+#   v # {'foo'=>'1'}
+#
+# However, to make life easier, lookups by key are converted to
+# strings (even when accessing the underlying hash directly):
+#
+#   {'foo'=>'bar'}.hstore[:foo] # 'bar'
+#   {'foo'=>'bar'}.hstore.to_hash[:foo] # 'bar'
+# 
+# HStore instances mostly just delegate to the underlying hash
+# instance, so Hash methods that modify the receiver or returned
+# modified copies of the receiver may not do string conversion.
+# The following methods will handle string conversion, and more
+# can be added later if desired:
+#
+# * \[\]
+# * \[\]=
+# * assoc (ruby 1.9 only)
+# * delete
+# * fetch
+# * has_key?
+# * has_value?
+# * include?
+# * key (ruby 1.9 only)
+# * key?
+# * member?
+# * merge
+# * merge!
+# * rassoc (ruby 1.9 only)
+# * replace
+# * store
+# * update
+# * value?
+#
+# If you want to insert a hash into an hstore database column:
+#
+#   DB[:table].insert(:column=>{'foo'=>'bar'}.hstore)
+#
+# If you would like to use hstore columns in your model objects, you
+# probably want to modify the schema parsing/typecasting so that it
+# recognizes and correctly handles the hstore columns, which you can
+# do by:
+#
+#   DB.extension :pg_hstore
+#
+# If you are not using the native postgres adapter, you probably
+# also want to use the typecast_on_load plugin in the model, and
+# set it to typecast the hstore column(s) on load.
+#
+# This extension requires the delegate and strscan libraries.
+
+require 'delegate'
+require 'strscan'
+
+module Sequel
+  module Postgres
+    class HStore < DelegateClass(Hash)
+      include Sequel::SQL::AliasMethods
+
+      # Parser for PostgreSQL hstore output format.
+      class Parser < StringScanner
+        QUOTE_RE = /"/.freeze
+        KV_SEP_RE = /"\s*=>\s*/.freeze
+        NULL_RE = /NULL/.freeze
+        SEP_RE = /,\s*/.freeze
+        QUOTED_RE = /(\\"|[^"])*/.freeze
+        REPLACE_RE = /\\(.)/.freeze
+        REPLACE_WITH = '\1'.freeze
+
+        # Parse the output format that PostgreSQL uses for hstore
+        # columns.  Note that this does not attempt to parse all
+        # input formats that PostgreSQL will accept.  For instance,
+        # it expects all keys and non-NULL values to be quoted.
+        #
+        # Return the resulting hash of objects.  This can be called
+        # multiple times, it will cache the parsed hash on the first
+        # call and use it for subsequent calls.
+        def parse
+          return @result if @result
+          hash = {}
+          while !eos?
+            skip(QUOTE_RE)
+            k = parse_quoted
+            skip(KV_SEP_RE)
+            if skip(QUOTE_RE)
+              v = parse_quoted
+              skip(QUOTE_RE)
+            else
+              scan(NULL_RE)
+              v = nil
+            end
+            skip(SEP_RE)
+            hash[k] = v
+          end
+          @result = hash
+        end
+          
+        private
+
+        # Parse and unescape a quoted key/value.
+        def parse_quoted
+          scan(QUOTED_RE).gsub(REPLACE_RE, REPLACE_WITH)
+        end
+      end
+
+      module DatabaseMethods
+        # Handle hstores in bound variables
+        def bound_variable_arg(arg, conn)
+          case arg
+          when HStore
+            arg.unquoted_literal
+          when Hash
+            HStore.new(arg).unquoted_literal
+          else
+            super
+          end
+        end
+
+        private
+
+        # Recognize the hstore database type.
+        def schema_column_type(db_type)
+          db_type == 'hstore' ? :hstore : super
+        end
+
+        # Typecast value correctly to HStore.  If already an
+        # HStore instance, return as is.  If a hash, return
+        # an HStore version of it.  If a string, assume it is
+        # in PostgreSQL output format and parse it using the
+        # parser.
+        def typecast_value_hstore(value)
+          case value
+          when HStore
+            value
+          when Hash
+            HStore.new(value)
+          else
+            raise Sequel::InvalidValue, "invalid value for hstore: #{value.inspect}"
+          end
+        end
+      end
+
+      # Default proc used for all underlying HStore hashes, so that even
+      # if you grab the underlying hash, it will still convert non-string
+      # keys to strings during lookup.
+      DEFAULT_PROC = lambda{|h, k| h[k.to_s] unless k.is_a?(String)}
+
+      QUOTE = '"'.freeze
+      COMMA = ",".freeze
+      KV_SEP = "=>".freeze
+      NULL = "NULL".freeze
+      ESCAPE_RE = /("|\\)/.freeze
+      ESCAPE_REPLACE = '\\\\\1'.freeze
+      HSTORE_CAST = '::hstore'.freeze
+
+      if RUBY_VERSION >= '1.9'
+        # Undef 1.9 marshal_{dump,load} methods in the delegate class,
+        # so that ruby 1.9 uses the old style _dump/_load methods defined
+        # in the delegate class, instead of the marshal_{dump,load} methods
+        # in the Hash class.
+        undef_method :marshal_load
+        undef_method :marshal_dump
+      end
+
+      # Use custom marshal loading, since underlying hash uses a default proc.
+      def self._load(args)
+        new(Hash[Marshal.load(args)])
+      end
+
+      # Parse the given string into an HStore, assuming the str is in PostgreSQL
+      # hstore output format.
+      def self.parse(str)
+        new(Parser.new(str).parse)
+      end
+
+      # Override methods that accept key argument to convert to string.
+      (%w'[] delete has_key? include? key? member?' + Array((%w'assoc' if RUBY_VERSION >= '1.9.0'))).each do |m|
+        class_eval("def #{m}(k) super(k.to_s) end", __FILE__, __LINE__)
+      end
+
+      # Override methods that accept value argument to convert to string unless nil.
+      (%w'has_value? value?' + Array((%w'key rassoc' if RUBY_VERSION >= '1.9.0'))).each do |m|
+        class_eval("def #{m}(v) super(convert_value(v)) end", __FILE__, __LINE__)
+      end
+
+      # Override methods that accept key and value arguments to convert to string appropriately.
+      %w'[]= store'.each do |m|
+        class_eval("def #{m}(k, v) super(k.to_s, convert_value(v)) end", __FILE__, __LINE__)
+      end
+
+      # Override methods that take hashes to convert the hashes to using strings for keys and
+      # values before using them.
+      %w'initialize merge! update replace'.each do |m|
+        class_eval("def #{m}(h, &block) super(convert_hash(h), &block) end", __FILE__, __LINE__)
+      end
+
+      # Use custom marshal dumping, since underlying hash uses a default proc.
+      def _dump(*)
+        Marshal.dump(to_a)
+      end
+
+      # Override to force the key argument to a string.
+      def fetch(key, *args, &block)
+        super(key.to_s, *args, &block)
+      end
+
+      # Convert the input hash to string keys and values before merging,
+      # and return a new HStore instance with the merged hash.
+      def merge(hash, &block)
+        self.class.new(super(convert_hash(hash), &block))
+      end
+
+      # Return the underlying hash used by this HStore instance.
+      alias to_hash __getobj__
+
+      # Append a literalize version of the hstore to the sql.
+      def sql_literal_append(ds, sql)
+        ds.literal_append(sql, unquoted_literal)
+        sql << HSTORE_CAST
+      end
+
+      # Return a string containing the unquoted, unstring-escaped
+      # literal version of the hstore.  Separated out for use by
+      # the bound argument code.
+      def unquoted_literal
+        str = ''
+        comma = false
+        commas = COMMA
+        quote = QUOTE
+        kv_sep = KV_SEP
+        null = NULL
+        each do |k, v|
+          str << commas if comma
+          str << quote << escape_value(k) << quote
+          str << kv_sep
+          if v.nil?
+            str << null
+          else
+            str << quote << escape_value(v) << quote
+          end
+          comma = true
+        end
+        str
+      end
+
+      private
+
+      # Return a new hash based on the input hash with string
+      # keys and string or nil values.
+      def convert_hash(h)
+        hash = Hash.new(&DEFAULT_PROC)
+        h.each{|k,v| hash[k.to_s] = convert_value(v)}
+        hash
+      end
+
+      # Return value v as a string unless it is already nil.
+      def convert_value(v)
+        v.to_s unless v.nil?
+      end
+
+      # Escape key/value strings when literalizing to
+      # correctly handle backslash and quote characters.
+      def escape_value(k)
+        k.to_s.gsub(ESCAPE_RE, ESCAPE_REPLACE)
+      end
+    end
+
+    PG_NAMED_TYPES = {} unless defined?(PG_NAMED_TYPES)
+    # Associate the named types by default.
+    PG_NAMED_TYPES[:hstore] = HStore.method(:parse)
+  end
+
+  module SQL::Builders
+    # Return a Postgres::HStore proxy for the given hash.
+    def hstore(v)
+      case v
+      when Postgres::HStore
+        v
+      when Hash
+        Postgres::HStore.new(v)
+      else
+        # May not be defined unless the pg_hstore_ops extension is used
+        hstore_op(v)
+      end
+    end
+  end
+
+  Database.register_extension(:pg_hstore, Postgres::HStore::DatabaseMethods)
+end
+
+if Sequel.core_extensions?
+  class Hash
+    # Create a new HStore using the receiver as the input
+    # hash.  Note that the HStore created will not use the
+    # receiver as the backing store, since it has to
+    # modify the hash.  To get the new backing store, use:
+    #
+    #   hash.hstore.to_hash
+    def hstore
+      Sequel::Postgres::HStore.new(self)
+    end
+  end
+end

data/lib/sequel/extensions/pg_hstore_ops.rb

@@ -0,0 +1,293 @@
+# The pg_hstore_ops extension adds support to Sequel's DSL to make
+# it easier to call PostgreSQL hstore functions and operators.
+#
+# To load the extension:
+#
+#   Sequel.extension :pg_hstore_ops
+#
+# The most common usage is taking an object that represents an SQL
+# expression (such as a :symbol), and calling Sequel.hstore_op with it:
+#
+#   h = Sequel.hstore_op(:hstore_column)
+#
+# If you have also loaded the pg_hstore extension, you can use
+# Sequel.hstore as well:
+#
+#   h = Sequel.hstore(:hstore_column)
+#
+# Also, on most Sequel expression objects, you can call the hstore 
+# method:
+#
+#   h = Sequel.expr(:hstore_column).hstore
+#
+# If you have loaded the {core_extensions extension}[link:files/doc/core_extensions_rdoc.html]),
+# you can also call Symbol#hstore:
+#
+#   h = :hstore_column.hstore
+#
+# This creates a Sequel::Postgres::HStoreOp object that can be used
+# for easier querying:
+#
+#   h - 'a'    # hstore_column - 'a'
+#   h['a']     # hstore_column -> 'a'
+#
+#   h.concat(:other_hstore_column)       # ||
+#   h.has_key?('a')                      # ?
+#   h.contain_all(:array_column)         # ?&
+#   h.contain_any(:array_column)         # ?|
+#   h.contains(:other_hstore_column)     # @> 
+#   h.contained_by(:other_hstore_column) # <@
+#
+#   h.defined        # defined(hstore_column)
+#   h.delete('a')    # delete(hstore_column, 'a')
+#   h.each           # each(hstore_column)
+#   h.keys           # akeys(hstore_column)
+#   h.populate(:a)   # populate_record(a, hstore_column)
+#   h.record_set(:a) # (a #= hstore_column)
+#   h.skeys          # skeys(hstore_column)
+#   h.slice(:a)      # slice(hstore_column, a)
+#   h.svals          # svals(hstore_column)
+#   h.to_array       # hstore_to_array(hstore_column)
+#   h.to_matrix      # hstore_to_matrix(hstore_column)
+#   h.values         # avals(hstore_column)
+#
+# See the PostgreSQL hstore function and operator documentation for more
+# details on what these functions and operators do.
+#
+# If you are also using the pg_hstore extension, you should load it before
+# loading this extension.  Doing so will allow you to use HStore#op to get
+# an HStoreOp, allowing you to perform hstore operations on hstore literals.
+
+module Sequel
+  module Postgres
+    # The HStoreOp class is a simple container for a single object that
+    # defines methods that yield Sequel expression objects representing
+    # PostgreSQL hstore operators and functions.
+    #
+    # In the method documentation examples, assume that:
+    #
+    #   hstore_op = :hstore.hstore
+    class HStoreOp < Sequel::SQL::Wrapper
+      CONCAT = ["(".freeze, " || ".freeze, ")".freeze].freeze
+      CONTAIN_ALL = ["(".freeze, " ?& ".freeze, ")".freeze].freeze
+      CONTAIN_ANY = ["(".freeze, " ?| ".freeze, ")".freeze].freeze
+      CONTAINS = ["(".freeze, " @> ".freeze, ")".freeze].freeze
+      CONTAINED_BY = ["(".freeze, " <@ ".freeze, ")".freeze].freeze
+      HAS_KEY = ["(".freeze, " ? ".freeze, ")".freeze].freeze
+      LOOKUP = ["(".freeze, " -> ".freeze, ")".freeze].freeze
+      RECORD_SET = ["(".freeze, " #= ".freeze, ")".freeze].freeze
+
+      # Delete entries from an hstore using the subtraction operator:
+      #
+      #   hstore_op - 'a' # (hstore - 'a')
+      def -(other)
+        HStoreOp.new(super)
+      end
+
+      # Lookup the value for the given key in an hstore:
+      #
+      #   hstore_op['a'] # (hstore -> 'a')
+      def [](key)
+        Sequel::SQL::StringExpression.new(:NOOP, Sequel::SQL::PlaceholderLiteralString.new(LOOKUP, [value, key]))
+      end
+
+      # Check if the receiver contains all of the keys in the given array:
+      #
+      #   hstore_op.contain_all(:a) # (hstore ?& a)
+      def contain_all(other)
+        bool_op(CONTAIN_ALL, other)
+      end
+
+      # Check if the receiver contains any of the keys in the given array:
+      #
+      #   hstore_op.contain_any(:a) # (hstore ?| a)
+      def contain_any(other)
+        bool_op(CONTAIN_ANY, other)
+      end
+
+      # Check if the receiver contains all entries in the other hstore:
+      #
+      #   hstore_op.contains(:h) # (hstore @> h)
+      def contains(other)
+        bool_op(CONTAINS, other)
+      end
+
+      # Check if the other hstore contains all entries in the receiver:
+      #
+      #   hstore_op.contained_by(:h) # (hstore <@ h)
+      def contained_by(other)
+        bool_op(CONTAINED_BY, other)
+      end
+
+      # Check if the receiver contains a non-NULL value for the given key:
+      #
+      #   hstore_op.defined('a') # defined(hstore, 'a')
+      def defined(key)
+        Sequel::SQL::BooleanExpression.new(:NOOP, function(:defined, key))
+      end
+
+      # Delete the matching entries from the receiver:
+      #
+      #   hstore_op.delete('a') # delete(hstore, 'a')
+      def delete(key)
+        HStoreOp.new(function(:delete, key))
+      end
+
+      # Transform the receiver into a set of keys and values:
+      #
+      #   hstore_op.each # each(hstore)
+      def each
+        function(:each)
+      end
+
+      # Check if the receiver contains the given key:
+      #
+      #   hstore_op.has_key?('a') # (hstore ? 'a')
+      def has_key?(key)
+        bool_op(HAS_KEY, key)
+      end
+      alias include? has_key?
+      alias key? has_key?
+      alias member? has_key?
+      alias exist? has_key?
+
+      # Return the receiver.
+      def hstore
+        self
+      end
+
+      # Return the keys as a PostgreSQL array:
+      #
+      #   hstore_op.keys # akeys(hstore)
+      def keys
+        function(:akeys)
+      end
+      alias akeys keys
+
+      # Merge a given hstore into the receiver:
+      #
+      #   hstore_op.merge(:a) # (hstore || a)
+      def merge(other)
+        HStoreOp.new(Sequel::SQL::PlaceholderLiteralString.new(CONCAT, [self, other]))
+      end
+      alias concat merge
+
+      # Create a new record populated with entries from the receiver:
+      #
+      #   hstore_op.populate(:a) # populate_record(a, hstore)
+      def populate(record)
+        SQL::Function.new(:populate_record, record, self)
+      end
+      
+      # Update the values in a record using entries in the receiver:
+      #
+      #   hstore_op.record_set(:a) # (a #= hstore)
+      def record_set(record)
+        Sequel::SQL::PlaceholderLiteralString.new(RECORD_SET, [record, value])
+      end
+
+      # Return the keys as a PostgreSQL set:
+      #
+      #   hstore_op.skeys # skeys(hstore)
+      def skeys
+        function(:skeys)
+      end
+
+      # Return an hstore with only the keys in the given array:
+      #
+      #   hstore_op.slice(:a) # slice(hstore, a)
+      def slice(keys)
+        HStoreOp.new(function(:slice, keys))
+      end
+
+      # Return the values as a PostgreSQL set:
+      #
+      #   hstore_op.svals # svals(hstore)
+      def svals
+        function(:svals)
+      end
+
+      # Return a flattened array of the receiver with alternating
+      # keys and values:
+      #
+      #   hstore_op.to_array # hstore_to_array(hstore)
+      def to_array
+        function(:hstore_to_array)
+      end
+
+      # Return a nested array of the receiver, with arrays of
+      # 2 element (key/value) arrays:
+      #
+      #   hstore_op.to_matrix # hstore_to_matrix(hstore)
+      def to_matrix
+        function(:hstore_to_matrix)
+      end
+
+      # Return the values as a PostgreSQL array:
+      #
+      #   hstore_op.values # avals(hstore)
+      def values
+        function(:avals)
+      end
+      alias avals values
+
+      private
+
+      # Return a placeholder literal with the given str and args, wrapped
+      # in a boolean expression, used by operators that return booleans.
+      def bool_op(str, other)
+        Sequel::SQL::BooleanExpression.new(:NOOP, Sequel::SQL::PlaceholderLiteralString.new(str, [value, other]))
+      end
+
+      # Return a function with the given name, and the receiver as the first
+      # argument, with any additional arguments given.
+      def function(name, *args)
+        SQL::Function.new(name, self, *args)
+      end
+    end
+
+    module HStoreOpMethods
+      # Wrap the receiver in an HStoreOp so you can easily use the PostgreSQL
+      # hstore functions and operators with it.
+      def hstore
+        HStoreOp.new(self)
+      end
+    end
+
+    if defined?(HStore)
+      class HStore
+        # Wrap the receiver in an HStoreOp so you can easily use the PostgreSQL
+        # hstore functions and operators with it.
+        def op
+          HStoreOp.new(self)
+        end
+      end
+    end
+  end
+
+  module SQL::Builders
+    # Return the object wrapped in an Postgres::HStoreOp.
+    def hstore_op(v)
+      case v
+      when Postgres::HStoreOp
+        v
+      else
+        Postgres::HStoreOp.new(v)
+      end
+    end
+  end
+
+  class SQL::GenericExpression
+    include Sequel::Postgres::HStoreOpMethods
+  end
+
+  class LiteralString
+    include Sequel::Postgres::HStoreOpMethods
+  end
+end
+
+if Sequel.core_extensions?
+  class Symbol
+    include Sequel::Postgres::HStoreOpMethods
+  end
+end