enummer 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f7599c1e54a52e62cd02fa52bda47b02b108193508575c9c7e4d46e7e67deb0
-  data.tar.gz: 9b26e5c4c28e8229519dd3eb1fed85c725d953472b7442b4291196740b7c6561
+  metadata.gz: adf5116258e6b0e0e5e3b4fc962f97228c26369c41c200a8af07dccd67f8d48e
+  data.tar.gz: ea4399838cf8e5cf8be9b23629b88af16c5355f0684d645a7f27db1d94fa642d
 SHA512:
-  metadata.gz: 647d8fa2a18291044340ba71dc0ba0524c1e838ae1bb2187b54321c27888a0daa433cdd6ce132e7743a41b365540fdc3aa054e1f7c37c8813b4dc9bf1f1dff09
-  data.tar.gz: 5530474e36838b2189ad4d138520bd689e792086e8a1d5661d1b0846db5d17511e535ec7fab0c6969cdb82223ec33801fb990a843c62a099cf0527de2f287771
+  metadata.gz: 328f419c099db1f1845c9e851fc7f85d7e26728d20ac2d400161ca8f0ba27738e835361499bb3e34f78b4be06b940cc1126d952d48a59cb9d287c6cd2d5cc9af
+  data.tar.gz: e119a0af64fa3318df0cfe09ff927c6e15780f592c13163565a6ce33cce7e61246a0395e97c86e7323de1829411efb5e25714959e6da98dbfcffe37824a1a6fd

data/README.md

@@ -1,17 +1,25 @@
 # Enummer
-Enummer is a lightweight answer for adding enums with multiple values to Rails, with a similar syntax to Rails' built-in `enum`. It officially supports only PostgreSQL and recent Rails versions because I don't really care about anything else, but PRs are welcome.
+
+[![Gem](https://img.shields.io/gem/v/enummer?color=green)](https://rubygems.org/gems/enummer)
+[![Codecov](https://img.shields.io/codecov/c/github/shkm/enummer/main)](https://app.codecov.io/gh/shkm/enummer)
+[![Licence](https://img.shields.io/github/license/shkm/enummer)](https://github.com/shkm/enummer/blob/main/MIT-LICENSE)
+[![Documentation](https://img.shields.io/badge/yard-docs-informational)](https://www.rubydoc.info/github/shkm/enummer/main)
+
+Enummer is a lightweight answer for adding enums with multiple values to Rails, with a similar syntax to Rails' built-in `enum`. At the moment it officially supports only PostgreSQL and recent Rails versions, though YMMV on another DBMS.
 
 ## Installation
 Add `gem "enummer"` to your Gemfile and `bundle`.
 
 ## Usage
-Create a migration for a bitstring that looks something like this:
+
+### Setup
+Create a migration for an integer that looks something like this:
 
 ```ruby
 class CreateUsers < ActiveRecord::Migration[7.0]
   def change
     create_table :users do |t|
-      t.column :permissions, "bit(8)"
+      t.integer :permissions, default: 0, null: false
     end
   end
 end
@@ -23,11 +31,55 @@ Now set up enummer with the available values in your model:
 enummer permissions: %i[read write execute]
 ```
 
-Note that the limit is currently **required** — do not use variable bit fields. 1 bit gets you 1 option.
+### Scopes
+
+Scopes will now be provided for `<option>` and `not_<option>`.
+
+```ruby
+User.read
+User.not_read
+User.write
+User.not_write
+User.execute
+User.not_execute
+```
+
+### Getter methods
+
+Simply calling the instance method for the column will return an array of options. Question mark methods are also provided.
+
+```ruby
+user = User.last
+
+user.permissions # => [:read, :write]
+
+user.read? # => true
+user.write? # => true
+user.execute? # => false
+```
+
+### Setter methods
+
+Options can be set with an array of symbols or via bang methods. Bang methods will additionally persist the changes.
+
+```ruby
+user.update(permissions: %i[read write])
+user.write!
+```
+
+## FAQ
+
+### Which data type should I use?
+That depends on how many options you expect to store. [In PostgreSQL](https://www.postgresql.org/docs/9.1/datatype-numeric.html) you should be able to store `bytes * 8 - 1` of your data type:
 
-*TODO*: a generator. Because.
+| Type     | Bytes | Values      |
+|----------|-------|-------------|
+| smallint | 2     | 15          |
+| integer  | 4     | 31          |
+| bigint   | 8     | 65          |
+| numeric  | ???   | all of them |
 
-## Usage outside of Rails
+### How can I use it outside of Rails?
 lol stop
 
 ## Contributing
@@ -36,6 +88,7 @@ Make an issue / PR and we'll see.
 ## Alternatives
 - [flag_shih_tzu](https://github.com/pboling/flag_shih_tzu)
 - Lots of booleans
+- DB Arrays
 
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/enummer/enummer_type.rb

@@ -4,30 +4,32 @@ require "active_record/type"
 
 module Enummer
   class EnummerType < ::ActiveRecord::Type::Value
-    attr_reader :bit_pairs
-
-    def initialize(value_names:, limit:)
+    # @param [Array<Symbol>] value_names list of all possible values for this type
+    def initialize(value_names:)
       @value_names = value_names
       @bit_pairs = determine_bit_pairs(value_names)
-      @limit = limit
     end
 
+    # @return Symbol Representation of this type
+    # @example
+    #   :enummer[read|write|execute]
     def type
       "enummer[#{@value_names.join("|")}]".to_sym
     end
 
+    # @param [Symbol|Array<Symbol>] value Current value represented as one or more symbols
+    # @return Numeric Numeric representation of values
     def serialize(value)
       return unless value
 
-      int = Array.wrap(value).sum { |value_name| @bit_pairs.fetch(value_name, 0) }
-
-      int.to_s(2).rjust(@limit, "0")
+      Array.wrap(value).sum { |value_name| @bit_pairs.fetch(value_name, 0) }
     end
 
+    # @param [Numeric] value Numeric representation of values
+    # @return [Array<Symbol>] Current value represented as symbols
     def deserialize(value)
       return [] unless value
 
-      value = value.to_i(2)
       @bit_pairs.each_with_object([]) do |(pair_name, pair_value), value_names|
         next if (value & pair_value).zero?
 

data/lib/enummer/extension.rb

@@ -2,6 +2,11 @@
 
 module Enummer
   module Extension
+    # @param [Hash] values The attribute name to options mapping for an multi-option enum
+    # @option values [Boolean|String] :_prefix The prefix to give to generated methods. If true, uses the attribute name.
+    # @option values [Boolean|String] :_suffix The suffix to give to generated methods. If true, uses the attribute name.
+    # @example Defining an enummer with a prefix. This would generate `#can_read?`, `#can_read=`, `#can_read!`, `.can_read`, etc.
+    #   enummer permissions: %i[read write execute], :_prefix: 'can'
     def enummer(values)
       options = {}
       options[:_prefix] = values.delete(:_prefix)
@@ -9,19 +14,25 @@ module Enummer
 
       name, values = values.first
 
-      limit = column_for_attribute(name).limit
-
-      attribute(name, :enummer, value_names: values, limit: limit)
+      attribute(name, :enummer, value_names: values)
 
       singleton_class.__send__(:define_method, name) { values }
 
-      _enummer_build_with_scope(name, values, limit)
-      _enummer_build_values(name, values, limit, options)
+      _enummer_build_with_scope(name, values)
+      _enummer_build_values(name, values, options)
     end
 
     private
 
-    def _enummer_build_values(attribute_name, value_names, limit, options)
+    def _enummer_build_with_scope(attribute_name, value_names)
+      scope "with_#{attribute_name}", lambda { |desired|
+        expected = Array.wrap(desired).sum(0) { |value| 1 << value_names.index(value) }
+
+        where("#{attribute_name} & :expected = :expected", expected: expected)
+      }
+    end
+
+    def _enummer_build_values(attribute_name, value_names, options)
       value_names.each_with_index do |name, i|
         method_name = _enummer_method_name(attribute_name, name, options)
 
@@ -37,23 +48,13 @@ module Enummer
           update(attribute_name => self[attribute_name] + [name])
         end
 
-        bit_position = limit - i - 1
+        bit = 1 << i
 
-        scope method_name, -> { where("get_bit(#{attribute_name}, ?) = 1", bit_position) }
-        scope "not_#{method_name}", -> { where("get_bit(#{attribute_name}, ?) = 0", bit_position) }
+        scope method_name, -> { where("#{attribute_name} & :bit = :bit", bit: bit) }
+        scope "not_#{method_name}", -> { where("#{attribute_name} & :bit != :bit", bit: bit) }
       end
     end
 
-    def _enummer_build_with_scope(attribute_name, value_names, limit)
-      scope "with_#{attribute_name}", lambda { |desired|
-        desired = Array.wrap(desired)
-
-        bitstring = (0..limit - 1).to_a.sum("") { |i| desired.include?(value_names[i]) ? "1" : "0" }.reverse
-
-        where("#{attribute_name} & :expected = :expected", expected: bitstring)
-      }
-    end
-
     def _enummer_method_name(attribute_name, value_name, options)
       prefix = _enummer_affix(attribute_name, options[:_prefix])
       suffix = _enummer_affix(attribute_name, options[:_suffix])

data/lib/enummer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Enummer
-  VERSION = "0.1.0"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: enummer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Jamie Schembri
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-30 00:00:00.000000000 Z
+date: 2022-02-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -24,7 +24,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 7.0.0
-description: Enummer implements multi-value enums with PostgreSQL bitstrings.
+description: Enummer implements multi-value enums with bitwise operations.
 email:
 - jamie@schembri.me
 executables: []
@@ -55,7 +55,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -65,5 +65,5 @@ requirements: []
 rubygems_version: 3.3.3
 signing_key:
 specification_version: 4
-summary: Multi-value enums for Rails
+summary: Multi-value enums for Rails.
 test_files: []