sequel 5.53.0 → 5.54.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7cd8e3e9c13b3f5593389d91fafe25706716cb7810187db2d1301efb2a99ee96
-  data.tar.gz: f5d92dc333425438d63598d19119dc7ff06a2635756a9970bff2be8d5252477b
+  metadata.gz: 3baaadc192f621e371699d654e998661db242d11385b328e5298ebfa7ce97d53
+  data.tar.gz: b6595670122d1ec5bbaccabef8d3af58a08f4d6edb6ffa782e34a1152d971143
 SHA512:
-  metadata.gz: 8e41100d1bec6bfa083ac57d52a4109bea07cda47d99c7b7b56e086489b36d9dde9361a3ee4b14795a11cdab4bc27d2fdb544a5df8bdc2e65c8df5a73bbf3ec0
-  data.tar.gz: 72be8971e7b44afb58b44115d654d24acb51c425b0019181ab495ffcd61ac23c497d108c6ed7982cddcb0c760270325a0cd1338f4265839bba571198f97e5ae2
+  metadata.gz: ebf7ff5a43c42d769a1f35e7c90f32c24e7776cde36c17c1800a4603b8173066bb90864b0644dfb6402221e1ed37ea36a9b026e6ab07e3086ed208eb6fb58d67
+  data.tar.gz: 82b525b77248038a08e2b247ae8de8028a1d4f67f332b267bd81f9d4087ebd900fcb58b1a7b9b82b20e3b93a00dd3a665d03dbe583ba94866c43663993c7436b

data/CHANGELOG

@@ -1,3 +1,7 @@
+=== 5.54.0 (2022-03-01)
+
+* Add enum plugin for treating columns as enums in a model (jeremyevans) (#1839)
+
 === 5.53.0 (2022-02-01)
 
 * Make Dataset#_sql_comment private when using the Database sql_comments extension (jeremyevans)

data/doc/release_notes/5.54.0.txt

@@ -0,0 +1,27 @@
+= New Feature
+
+* An enum plugin has been added.  This plugin allows you to create
+  model-level enums, giving names to underlying values of a column.
+  For example:
+
+    Album.plugin :enum
+    Album.enum :status_id, good: 1, bad: 2
+
+  Adds Album#good! and Album#bad! for changing the status_id to 1 or 
+  2 respectively.  It adds Album#good? and Album#bad? for checking
+  whether the status_id is 1 or 2 respectively.  It overrides
+  Album#status_id to return :good or :bad instead of 1 or 2,
+  respectively, and overrides Album#status_id= to accept :good or
+  :bad instead of 1 or 2 respectively.
+
+  Additionally, it adds good and bad dataset methods for filtering
+  the model's dataset to records where status_id is 1 or 2
+  respectively. It also adds not_good and not_bad dataset methods
+  for filtering the model's dataset to records where status_id is not
+  1 or not 2 respectively.
+
+  You can use :prefix and :suffix options when calling enum to
+  add a prefix or suffix to the method names created.  You can
+  set the :override_accessors option to false to not override
+  the accessor methods for the column, and set the :dataset_methods
+  option to false to not add dataset methods.

data/lib/sequel/plugins/enum.rb

@@ -0,0 +1,124 @@
+# frozen-string-literal: true
+
+module Sequel
+  module Plugins
+    # The enum plugin allows for easily adding methods to modify the value of
+    # a column.  It allows treating the column itself as an enum, returning a
+    # symbol for the related enum value.  It also allows for setting up dataset
+    # methods to easily find records having or not having each enum value.
+    #
+    # After loading the plugin, you can call the +enum+ method to define the
+    # methods.  The +enum+ method accepts a symbol for the underlying
+    # database column, and a hash with symbol keys for the enum values.
+    # For example, the following call:
+    #
+    #   Album.enum :status_id, good: 1, bad: 2
+    #
+    # Will define the following instance methods:
+    #
+    # Album#good! :: Change +status_id+ to +1+ (does not save the receiver)
+    # Album#bad! :: Change +status_id+ to +2+ (does not save the receiver)
+    # Album#good? :: Return whether +status_id+ is +1+
+    # Album#bad? :: Return whether +status_id+ is +2+
+    #
+    # It will override the following instance methods:
+    #
+    # Album#status_id :: Return +:good+/+:bad+ instead of +1+/+2+ (other values returned as-is)
+    # Album#status_id= :: Allow calling with +:good+/+:bad+ to set +status_id+ to +1+/+2+ (other values,
+    #                     such as <tt>'good'</tt>/<tt>'bad'</tt> set as-is)
+    #
+    # If will define the following dataset methods:
+    #
+    # Album.dataset.good :: Return a dataset filtered to rows where +status_id+ is +1+
+    # Album.dataset.not_good :: Return a dataset filtered to rows where +status_id+ is not +1+
+    # Album.dataset.bad:: Return a dataset filtered to rows where +status_id+ is +2+
+    # Album.dataset.not_bad:: Return a dataset filtered to rows where +status_id+ is not +2+
+    #
+    # When calling +enum+, you can also provide the following options:
+    #
+    # :prefix :: Use a prefix for methods defined for each enum value. If +true+ is provided at the value, use the column name as the prefix.
+    #            For example, with <tt>prefix: 'status'</tt>, the instance methods defined above would be +status_good?+, +status_bad?+,
+    #            +status_good!+, and +status_bad!+, and the dataset methods defined would be +status_good+, +status_not_good+, +status_bad+,
+    #            and +status_not_bad+.
+    # :suffix :: Use a suffix for methods defined for each enum value. If +true+ is provided at the value, use the column name as the suffix.
+    #            For example, with <tt>suffix: 'status'</tt>, the instance methods defined above would be +good_status?+, +bad_status?+,
+    #            +good_status!+, and +bad_status!+, and the dataset methods defined would be +good_status+, +not_good_status+, +bad_status+,
+    #            and +not_bad_status+.
+    # :override_accessors :: Set to +false+ to not override the column accessor methods.
+    # :dataset_methods :: Set to +false+ to not define dataset methods.
+    #
+    # Note that this does not use a true enum column in the database.  If you are
+    # looking for enum support in the database, and your are using PostgreSQL,
+    # Sequel supports that via the pg_enum Database extension.
+    #
+    # Usage:
+    #
+    #   # Make all model subclasses handle enums
+    #   Sequel::Model.plugin :enum
+    #
+    #   # Make the Album class handle enums
+    #   Album.plugin :enum
+    module Enum
+      module ClassMethods
+        # Define instance and dataset methods in this class to treat column
+        # as a enum.  See Enum documentation for usage.
+        def enum(column, values, opts=OPTS)
+          raise Sequel::Error, "enum column must be a symbol" unless column.is_a?(Symbol)
+          raise Sequel::Error, "enum values must be provided as a hash with symbol keys" unless values.is_a?(Hash) && values.all?{|k,| k.is_a?(Symbol)}
+
+          if prefix = opts[:prefix]
+            prefix = column if prefix == true
+            prefix = "#{prefix}_"
+          end
+
+          if suffix = opts[:suffix]
+            suffix = column if suffix == true
+            suffix = "_#{suffix}"
+          end
+          
+          values = Hash[values].freeze
+          inverted = values.invert.freeze
+
+          unless @enum_methods
+            @enum_methods = Module.new
+            include @enum_methods
+          end
+
+          @enum_methods.module_eval do
+            unless opts[:override_accessors] == false
+              define_method(column) do
+                v = super()
+                inverted.fetch(v, v)
+              end
+
+              define_method(:"#{column}=") do |v|
+                super(values.fetch(v, v))
+              end
+            end
+
+            values.each do |key, value|
+              define_method(:"#{prefix}#{key}#{suffix}!") do
+                self[column] = value
+                nil
+              end
+
+              define_method(:"#{prefix}#{key}#{suffix}?") do
+                self[column] == value
+              end
+            end
+          end
+
+          unless opts[:dataset_methods] == false
+            dataset_module do
+              values.each do |key, value|
+                cond = Sequel[column=>value]
+                where :"#{prefix}#{key}#{suffix}", cond
+                where :"#{prefix}not_#{key}#{suffix}", ~cond
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sequel/version.rb

@@ -6,7 +6,7 @@ module Sequel
 
   # The minor version of Sequel.  Bumped for every non-patch level
   # release, generally around once a month.
-  MINOR = 53
+  MINOR = 54
 
   # The tiny version of Sequel.  Usually 0, only bumped for bugfix
   # releases that fix regressions from previous versions.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sequel
 version: !ruby/object:Gem::Version
-  version: 5.53.0
+  version: 5.54.0
 platform: ruby
 authors:
 - Jeremy Evans
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-02-01 00:00:00.000000000 Z
+date: 2022-03-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -198,6 +198,7 @@ extra_rdoc_files:
 - doc/release_notes/5.51.0.txt
 - doc/release_notes/5.52.0.txt
 - doc/release_notes/5.53.0.txt
+- doc/release_notes/5.54.0.txt
 - doc/release_notes/5.6.0.txt
 - doc/release_notes/5.7.0.txt
 - doc/release_notes/5.8.0.txt
@@ -279,6 +280,7 @@ files:
 - doc/release_notes/5.51.0.txt
 - doc/release_notes/5.52.0.txt
 - doc/release_notes/5.53.0.txt
+- doc/release_notes/5.54.0.txt
 - doc/release_notes/5.6.0.txt
 - doc/release_notes/5.7.0.txt
 - doc/release_notes/5.8.0.txt
@@ -501,6 +503,7 @@ files:
 - lib/sequel/plugins/eager_each.rb
 - lib/sequel/plugins/eager_graph_eager.rb
 - lib/sequel/plugins/empty_failure_backtraces.rb
+- lib/sequel/plugins/enum.rb
 - lib/sequel/plugins/error_splitter.rb
 - lib/sequel/plugins/finder.rb
 - lib/sequel/plugins/forbid_lazy_load.rb
@@ -594,7 +597,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.3.7
 signing_key: 
 specification_version: 4
 summary: The Database Toolkit for Ruby