bitmask_enum 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8b142602ee1da79ca17074c2fe1edcabeb98d5a053c2486f98ef95410a6f0b15
+  data.tar.gz: fa1d5994dd353bd811ed560f1fbbb204d7d8fe2ff824280c8b4dc689592fb72e
+SHA512:
+  metadata.gz: 0bf71ad17b882b72b65f90902c54c8ecf2e2c6589acb4fd90b8b4f586d02b5caa20d2500a0a0b880ea10045048dae6062d5346801a6b0d89c6048dca3908f9e4
+  data.tar.gz: 4fc29a681c368a0808d4554fd74e448a28cf24486a81d0488d765add4124e38ce1e40ffeddcf38bedad81579813103bf58fc52e3d3feb38dc63c25aacb8c812b

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.rspec_status
+*.gem

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,14 @@
+require:
+  - rubocop-rspec
+
+AllCops:
+  SuggestExtensions: false
+  NewCops: enable
+  TargetRubyVersion: 2.4
+
+Metrics/MethodLength: 
+  Max: 20
+RSpec/ExampleLength:
+  Max: 10
+RSpec/NestedGroups:
+  Max: 4

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.6.10
+before_install: gem install bundler -v 1.17.2

data/CHANGELOG.md

@@ -0,0 +1,39 @@
+# BitmaskEnum changelog
+
+## 0.1.0 : 2022-08-28
+
+Initial build. Pre-release.
+
+Checking and setting of flags on model instance.
+Scopes for querying.
+
+## 0.2.0 : 2022-08-28
+
+Pre-release.
+
+Refactor of underlying logic. 
+Enforce symbols in method output.
+
+## 0.3.0 : 2022-08-28
+
+Pre-release.
+
+Refactor logic and tests.
+Switch bitmask_enum params to a single hash with multiple keys.
+
+## 0.4.0 : 2022-08-28
+
+Pre-release.
+
+Add nil handling.
+Refactor options and add testing for them.
+
+## 1.0.0 : 2022-08-29
+
+Release.
+
+Add setter override to write flags as flag values.
+Add YARD docs.
+Standardize output to symbols.
+Add validation of the attribute - less_than: 1 << flags.size
+Add max ActiveRecord version to protect against future breaking releases

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at lucygilbert01@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,82 @@
+PATH
+  remote: .
+  specs:
+    bitmask_enum (1.0.0)
+      activerecord (>= 4.2, <= 7.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (6.1.6.1)
+      activesupport (= 6.1.6.1)
+    activerecord (6.1.6.1)
+      activemodel (= 6.1.6.1)
+      activesupport (= 6.1.6.1)
+    activesupport (6.1.6.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    ast (2.4.2)
+    concurrent-ruby (1.1.10)
+    diff-lcs (1.5.0)
+    i18n (1.12.0)
+      concurrent-ruby (~> 1.0)
+    json (2.6.2)
+    minitest (5.16.3)
+    parallel (1.22.1)
+    parser (3.1.2.1)
+      ast (~> 2.4.1)
+    rainbow (3.1.1)
+    rake (10.5.0)
+    regexp_parser (2.5.0)
+    rexml (3.2.5)
+    rspec (3.11.0)
+      rspec-core (~> 3.11.0)
+      rspec-expectations (~> 3.11.0)
+      rspec-mocks (~> 3.11.0)
+    rspec-core (3.11.0)
+      rspec-support (~> 3.11.0)
+    rspec-expectations (3.11.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.11.0)
+    rspec-mocks (3.11.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.11.0)
+    rspec-support (3.11.0)
+    rubocop (1.35.1)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.1.2.1)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.20.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.21.0)
+      parser (>= 3.1.1.0)
+    rubocop-rspec (2.12.1)
+      rubocop (~> 1.31)
+    ruby-progressbar (1.11.0)
+    sqlite3 (1.4.4)
+    tzinfo (2.0.5)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.2.0)
+    zeitwerk (2.6.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bitmask_enum!
+  bundler (~> 1.17)
+  rake (~> 10.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.35)
+  rubocop-rspec (~> 2.12)
+  sqlite3 (~> 1.4)
+
+BUNDLED WITH
+   1.17.2

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Lucy Gilbert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,203 @@
+# BitmaskEnum
+
+A bitmask enum attribute for ActiveRecord.
+
+Aiming to be lightweight and performant, providing the core functionality for the use of a bitmask enum model attribute.
+
+It adds checking, getting, setting and toggling of the flags to the instance; scopes for flags to the class; and allows creating/updating the attribute with a flag/an array of flags rather than an integer.
+
+Supporting Ruby 2.4+ and Rails 4.2+.
+
+Credit is due to Joel Moss' gem [bitmask_attributes](https://github.com/joelmoss/bitmask_attributes). I came across it while considering if I should write a gem for this. It's great work and some elements of it inspired this gem, I just had my own thoughts about how I'd like the gem to operate, and wanted some more end-to-end experience on gem production so I decided to create this rather than pick up the torch on that repo.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'bitmask_enum'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install bitmask_enum
+
+## Usage
+
+In the model, the bitmask enum is added in a similar way to enums. Given an integer attribute called `attribs`, flags of `flag` and `flag2`, adding the `flag_prefix` option with the value `type`, the following line would be used:
+
+```ruby
+bitmask_enum attribs: [:flag, :flag2], flag_prefix: 'type'
+```
+
+The `bitmask_enum` class method is used to add the bitmask enum, which then goes on to add numerous helper methods to the model.
+
+It also enables setting the attribute with a flag or array of flags when creating or updating. More info is in the `{attribute}=` method section.
+```ruby
+Model.create!(attribs: :flag)
+Model.update!(attribs: [:flag, :flag2])
+```
+
+### `bitmask_enum`
+
+`bitmask_enum params`
+
+#### params
+
+**Type:** Hash
+
+The first key of this hash should be the name of the integer attribute to be modeled as a bitmask enum. The value of that key should be an array of symbols or strings representing the flags that will be part of the bitmask.
+
+Any following keys are optional and should define options for the enum. The current accepted keys are:
+- `flag_prefix` - A symbol or string that will prefix all the created method names for individual flags
+  - The gem will prepend the provided value to the flag with an underscore, e.g. `pre` would become `pre_flag`
+- `flag_suffix` - A symbol or string that will suffix all the created method names for individual flags
+  - The gem will append the provided value to the flag with an underscore, e.g. `post` would become `flag_post`
+- `nil_handling` - A symbol or string that signifies which behaviour to use when handling nil attribute values
+  - The default value, used if the option is not supplied, is `:include`. This includes nil attribute rows as if they were 0.
+  - There are currently no other options but more are planned.
+  - Providing an unrecognized option will raise an error.
+- `validate` - A boolean signaling whether you want to apply attribute validation. Attributes will validate that they are less than the number of flags squared (number of flags squared - 1 is the highest valid bitmask value). Defaults to `true`.
+
+---
+
+### The following methods will be created on the model instance:
+
+### `{flag}?`
+
+**No params**
+
+For each flag, this method will be created.
+
+The method checks whether a flag is enabled or not.
+
+**Return value:** `boolean` - reflects whether the flag is enabled for the instance.
+
+### `{flag}!`
+
+**No params**
+
+For each flag, this method will be created.
+
+The method toggles the current setting of the flag.
+
+**Return value:** `boolean` - true if the update of the attribute was successful. Raises error if update was unsuccessful.
+
+### `enable_{flag}!`
+
+**No params**
+
+For each flag, this method will be created.
+
+The method enables the the flag is it is disabled, otherwise it takes no action.
+
+**Return value:** `boolean` - true if the update of the attribute was successful. Raises error if update was unsuccessful.
+
+### `disable_{flag}!`
+
+**No params**
+
+For each flag, this method will be created.
+
+The method disables the the flag is it is enabled, otherwise it takes no action.
+
+**Return value:** `boolean` - true if the update of the attribute was successful. Raises error if update was unsuccessful.
+
+### `{attribute}_settings`
+
+**No params**
+
+This method will be created once on the instance.
+
+The method returns a hash with the flags as keys and their current settings as values. The keys will be symbols.
+
+**Return value:** `hash` - hash with flags as keys and their current settings as values. E.g. `{ flag_one: true, flag_two: false }`
+
+### `{attribute}` (_Override_)
+
+**No params**
+
+This method will be created once on the instance.
+
+The method returns an array of all enabled flags on the instance. The items will be symbols. This is the attribute getter.
+
+**Return value:** `array` - array of enabled flags. E.g. `[:flag_one, :flag_two]`
+
+### `{attribute}=` (_Override_)
+
+**No params**
+
+This method will be created once on the instance.
+
+The method sets the attribute to the provided value - either an integer, a symbol or string representing a flag or an array of symbols or strings. This is the attribute setter.
+
+This method will raise an ArgumentError if one of the flag values passed is not one that was defined.
+
+**Return value:** `array` - array of enabled flags. E.g. `[:flag_one, :flag_two]`
+
+---
+
+### The following methods will be created on the model class:
+
+### `{flag}_enabled`
+
+**No params**
+
+For each flag, this method will be created on the class.
+
+The method is a scope of all records for which the flag is enabled.
+
+**Return value:** `ActiveRecord::Relation` - a collection of all records for which the flag is enabled.
+
+### `{flag}_disabled`
+
+**No params**
+
+For each flag, this method will be created on the class.
+
+The method is a scope of all records for which the flag is disabled.
+
+**Return value:** `ActiveRecord::Relation` - a collection of all records for which the flag is disabled.
+
+### `{attribute}`
+
+**No params**
+
+This method will be created once on the class.
+
+The method returns an array of all the defined flags. The items will be symbols.
+
+**Return value:** `array` - array of defined flags. E.g. `[:flag_one, :flag_two]`
+
+## Manual testing
+
+This gem has been tested and found to be generally functional with the following combinations: (but it should work with any combination of Ruby 2.4+ and Rails 4.2+, theoretically it could go lower but those are already 8 years old so I felt it was sufficient.)
+
+- Ruby 2.4.10 & Rails 4.2.11.3
+- Ruby 2.6.10 & Rails 4.2.11.3
+- Ruby 2.6.10 & Rails 5.2.8.1
+- Ruby 3.1.2 & Rails 7.0.3.1
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/lucygilbert/bitmask_enum. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+1. Fork the repo.
+2. Run `bin/setup` to install the bundle and set up the pre-commit hook.
+  - If the output ends with `SUCCESS.`, the pre-commit hook has been applied correctly.
+  - If the output ends with `ERROR!`, applying the pre-commit hook has failed. Please check the error and install manually.
+3. Create a branch, prefixed with `feature/` if this addition is a new feature, or `bugfix/` if the addition is a bug fix.
+4. Add your code with ample testing and ensure that tests and linting pass for your commit.
+5. Push the branch to your fork and raise a PR against the main repo.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the BitmaskEnum project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/bitmask_enum/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/setup

@@ -0,0 +1,8 @@
+#!/bin/sh
+
+bundle install
+if cp -f pre-commit .git/hooks/; then
+  echo '\033[0;32mPre-commit copied to .git/hooks!\nSUCCESS.\033[0;0m'
+else
+  echo '\033[0;31mPre-commit copy failed! Ensure the pre-commit is enabled before continuing.\nERROR!\033[0;0m'
+fi

data/bitmask_enum.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'bitmask_enum/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'bitmask_enum'
+  spec.version       = BitmaskEnum::VERSION
+  spec.authors       = ['Lucy Gilbert']
+  spec.email         = ['lucygilbert01@gmail.com']
+
+  spec.summary       = 'A bitmask enum attribute for ActiveRecord'
+  spec.homepage      = 'https://github.com/lucygilbert/bitmask_enum'
+  spec.license       = 'MIT'
+
+  raise 'RubyGems 2+ required to guard against public gem pushes' unless spec.respond_to?(:metadata)
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org/'
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/master/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^spec/}) }
+  end
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 2.4'
+
+  spec.add_dependency 'activerecord', '>= 4.2', '<=7.0'
+  spec.add_development_dependency 'bundler', '~> 1.17'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 1.35'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.12'
+  spec.add_development_dependency 'sqlite3', '~> 1.4'
+end

data/lib/bitmask_enum/attribute.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'bitmask_enum/conflict_checker'
+require 'bitmask_enum/options'
+require 'bitmask_enum/nil_handler'
+require 'bitmask_enum/eval_scripts'
+
+module BitmaskEnum
+  # Constructs the magic methods and overrides getters and setters for a bitmask enum attribute
+  # @api private
+  class Attribute
+    def initialize(model, attribute, flags, options, defined_enum_methods)
+      @attribute = attribute
+      @flags = flags
+      @options = Options.new(options)
+      @nil_handler = NilHandler.new(@options.nil_handling)
+      @model = model
+      @conflict_checker = ConflictChecker.new(model, attribute, defined_enum_methods)
+    end
+
+    # Defines the methods for the attribute
+    def construct!
+      attribute_validation if @options.validate
+
+      @flags.each_with_index do |flag, flag_index|
+        per_flag_methods("#{@options.flag_prefix}#{flag}#{@options.flag_suffix}", flag_index)
+      end
+
+      flag_settings_hash_method
+      flag_getter_method
+      flag_setter_method
+
+      class_flag_values_method
+    end
+
+    private
+
+    def attribute_validation
+      @model.class_eval EvalScripts.attribute_validation(@attribute, @flags.size), __FILE__, __LINE__
+    end
+
+    def per_flag_methods(flag_label, flag_index)
+      flag_check_method(flag_label, flag_index)
+      flag_toggle_method(flag_label, flag_index)
+      flag_on_method(flag_label, flag_index)
+      flag_off_method(flag_label, flag_index)
+
+      class_flag_enabled_scope(flag_label, flag_index)
+      class_flag_disabled_scope(flag_label, flag_index)
+    end
+
+    def flag_check_method(flag_label, flag_index)
+      flag_method("#{flag_label}?", "(#{@nil_handler.in_attribute_eval(@attribute)} & #{1 << flag_index}).positive?")
+    end
+
+    def flag_toggle_method(flag_label, flag_index)
+      flag_method(
+        "#{flag_label}!",
+        "update!('#{@attribute}' => #{@nil_handler.in_attribute_eval(@attribute)} ^ #{1 << flag_index})"
+      )
+    end
+
+    def flag_on_method(flag_label, flag_index)
+      flag_method(
+        "enable_#{flag_label}!",
+        "update!('#{@attribute}' => #{@nil_handler.in_attribute_eval(@attribute)} | #{1 << flag_index})"
+      )
+    end
+
+    def flag_off_method(flag_label, flag_index)
+      flag_method(
+        "disable_#{flag_label}!",
+        "update!('#{@attribute}' => #{@nil_handler.in_attribute_eval(@attribute)} & #{~(1 << flag_index)})"
+      )
+    end
+
+    def flag_method(method_name, method_code)
+      @conflict_checker.check_instance_method!(method_name)
+
+      @model.class_eval EvalScripts.flag_method(method_name, method_code), __FILE__, __LINE__
+    end
+
+    def class_flag_enabled_scope(flag_label, flag_index)
+      class_flag_scope("#{flag_label}_enabled", :on, flag_index)
+    end
+
+    def class_flag_disabled_scope(flag_label, flag_index)
+      class_flag_scope("#{flag_label}_disabled", :off, flag_index)
+    end
+
+    def class_flag_scope(scope_name, setting, flag_index)
+      comparator = setting == :on ? :> : :==
+      values_for_bitmask = (0...(1 << @flags.size)).select { |x| (x & (1 << flag_index)).send(comparator, 0) }
+
+      values_for_bitmask = @nil_handler.in_array(values_for_bitmask) if setting == :off
+
+      @conflict_checker.check_class_method!(scope_name)
+
+      @model.class_eval EvalScripts.flag_scope(scope_name, @attribute, values_for_bitmask), __FILE__, __LINE__
+    end
+
+    def flag_settings_hash_method
+      method_name = "#{@attribute}_settings"
+
+      @conflict_checker.check_instance_method!(method_name)
+
+      flag_hash_contents = @flags.each_with_index.map do |flag, flag_index|
+        "#{flag}: (#{@nil_handler.in_attribute_eval(@attribute)} & #{1 << flag_index}).positive?"
+      end.join(', ')
+      @model.class_eval EvalScripts.flag_settings(method_name, flag_hash_contents), __FILE__, __LINE__
+    end
+
+    def flag_getter_method
+      @conflict_checker.check_instance_method!(@attribute)
+
+      flag_array_contents = @flags.each_with_index.map do |flag, flag_index|
+        "(#{@nil_handler.in_attribute_eval(@attribute)} & #{1 << flag_index}).positive? ? :#{flag} : nil"
+      end.join(', ')
+      @model.class_eval EvalScripts.flag_getter(@attribute, flag_array_contents), __FILE__, __LINE__
+    end
+
+    def flag_setter_method
+      method_name = "#{@attribute}="
+
+      @conflict_checker.check_instance_method!(method_name)
+
+      @model.class_eval EvalScripts.flag_setter(method_name, @attribute), __FILE__, __LINE__
+    end
+
+    def class_flag_values_method
+      @conflict_checker.check_class_method!(@attribute)
+
+      @model.class_eval EvalScripts.class_flag_values(@attribute, @flags), __FILE__, __LINE__
+    end
+  end
+end

data/lib/bitmask_enum/conflict_checker.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'bitmask_enum/errors'
+
+module BitmaskEnum
+  # Checks for method conflicts on the model
+  # @api private
+  class ConflictChecker
+    def initialize(model, attribute, defined_enum_methods)
+      @model = model
+      @attribute = attribute
+      @defined_enum_methods = defined_enum_methods
+    end
+
+    # Check if the method name is dangerous or already defined on the class
+    # @param method_name [String] Name of the method
+    def check_class_method!(method_name)
+      if @model.dangerous_class_method?(method_name)
+        raise_bitmask_conflict_error!(ActiveRecord.name, method_name, klass_method: true)
+      elsif @model.method_defined_within?(method_name, ActiveRecord::Relation)
+        raise_bitmask_conflict_error!(ActiveRecord::Relation.name, method_name, klass_method: true)
+      end
+    end
+
+    # Check if the method name is dangerous or already defined on the instance, or defined by another bitmask enum
+    # @param method_name [String] Name of the method
+    def check_instance_method!(method_name)
+      if @model.dangerous_attribute_method?(method_name)
+        raise_bitmask_conflict_error!(ActiveRecord.name, method_name)
+      elsif @defined_enum_methods.include?(method_name)
+        raise_bitmask_conflict_error!(@defined_enum_methods[method_name], method_name)
+      end
+
+      @defined_enum_methods[method_name] = @attribute
+    end
+
+    private
+
+    def raise_bitmask_conflict_error!(source, method_name, klass_method: false)
+      raise BitmaskEnumMethodConflictError.new(source, @model.name, @attribute, method_name, klass_method)
+    end
+  end
+end

data/lib/bitmask_enum/errors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module BitmaskEnum
+  # Error for an invalid definition of the bitmask enum
+  # @api private
+  class BitmaskEnumInvalidError < ArgumentError
+    def initialize(detail)
+      super("BitmaskEnum definition is invalid: #{detail}")
+    end
+  end
+
+  # Error for a conflicting method that would be generated by the enum
+  # @api private
+  class BitmaskEnumMethodConflictError < ArgumentError
+    def initialize(source, klass, attribute, method_name, klass_method)
+      super(
+        'BitmaskEnum method definition is conflicting: ' \
+        "#{klass_method ? 'class ' : ''}method: #{method_name} " \
+        "for enum: #{attribute} in class: #{klass} is already defined by: #{source}"
+      )
+    end
+  end
+end

data/lib/bitmask_enum/eval_scripts.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module BitmaskEnum
+  # Code strings to be templated and evaled to create methods
+  # @api private
+  module EvalScripts
+    class << self
+      # Code for validation method checking attribute is within valid values
+      # @param attribute [String] Name of the attribute
+      # @param flags_size [Integer] Number of defined flags
+      # @return [String] Code string to be evaled
+      def attribute_validation(attribute, flags_size)
+        %(
+          validates(                                          # validates(
+            :#{attribute},                                    #   :attribs,
+            numericality: { less_than: (1 << #{flags_size}) } #   numericality: { less_than: (1 << 3) }
+          )                                                   # )
+        )
+      end
+
+      # Code for methods checking and setting flags: `#flag?`, `#flag!`, `#enable_flag!`, `#disable_flag!`
+      # @param method_name [String] Name of the method
+      # @param method_code [String] Code contents of the method
+      # @return [String] Code string to be evaled
+      def flag_method(method_name, method_code)
+        %(
+          def #{method_name}  # def flag!
+            #{method_code}    #   update!('attribs' => self['attribs'] ^ 1)
+          end                 # end
+        )
+      end
+
+      # Code for methods scoping by flag: `.flag_enabled`, `.flag_disabled`
+      # @param scope_name [String] Name of the scope
+      # @param attribute [String] Name of the attribute
+      # @param values_for_bitmask [Array] Array of integers for which the flag would be disabled
+      # @return [String] Code string to be evaled
+      def flag_scope(scope_name, attribute, values_for_bitmask)
+        %(
+          scope :#{scope_name}, -> do                       # scope :flag_disabled, -> do
+            where('#{attribute}' => #{values_for_bitmask})  #   where('attribs' => [0, 2, 4])
+          end                                               # end
+        )
+      end
+
+      # Code for method returning hash of flags with their boolean setting: `#attribs_settings`
+      # @param method_name [String] Name of the method
+      # @param flag_hash_contents [String] Contents of the hash which provides the flag settings
+      # @return [String] The code string to be evaled
+      def flag_settings(method_name, flag_hash_contents)
+        %(
+          def #{method_name}          # def attribs_settings
+            { #{flag_hash_contents} } #   { flag: (self['attribs'] & 1).positive? }
+          end                         # end
+        )
+      end
+
+      # Code for attribute getter method: `#attribs`
+      # The return value of the method will be an array of symbols representing the enabled flags
+      # @param attribute [String] Name of the attribute
+      # @param flag_array_contents [String] Contents of the array which provides the enabled flags
+      # @return [String] The code string to be evaled
+      def flag_getter(attribute, flag_array_contents)
+        %(
+          def #{attribute}                    # def attribs
+            [#{flag_array_contents}].compact  #   [((self['attribs'] || 0) & 1).positive? ? :flag : nil].compact
+          end                                 # end
+        )
+      end
+
+      # Code for attribute setter method: `#attribs=`
+      # The method will take an integer, a symbol representing a flag or an array of symbols representing flags
+      # @param method_name [String] Name of the method (the attribute name with an =)
+      # @param attribute [String] Name of the attribute
+      # @return [String] The code string to be evaled
+      def flag_setter(method_name, attribute)
+        %(
+def #{method_name}(value)                                     # def attribs=(value)
+  if value.is_a?(Integer)                                     #   if value.is_a?(Integer)
+    super                                                     #     super
+  else                                                        #   else
+    super(Array(value).reduce(0) do |acc, flag|               #     super(Array(value).reduce(0) do |acc, x|
+      flag_index = self.class.#{attribute}.index(flag.to_sym) #       flag_index = self.class.attribs.index(flag.to_sym)
+      if flag_index.nil?                                      #       if flag_index.nil?
+        raise(                                                #         raise(
+          ArgumentError,                                      #           ArgumentError,
+          "Invalid flag \#{flag} for #{attribute}"            #           "Invalid flag \#{flag} for attribs"
+        )                                                     #         )
+      end                                                     #       end
+      acc | (1 << flag_index)                                 #       acc | (1 << flag_index)
+    end)                                                      #     end)
+  end                                                         #   end
+end                                                           # end
+        )
+      end
+
+      # Code for class attribute values method: `#attribs=`
+      # The return value of the method will be an array of symbols representing all defined flags
+      # @param attribute [String] Name of the attribute
+      # @param flags [String] Array of symbols representing all defined flags
+      # @return [String] The code string to be evaled
+      def class_flag_values(attribute, flags)
+        %(
+          def self.#{attribute}  # def self.attribs
+            #{flags}             #   [:flag]
+          end                    # end
+        )
+      end
+    end
+  end
+end

data/lib/bitmask_enum/nil_handler.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module BitmaskEnum
+  # Handles nil attribute values
+  # @api private
+  class NilHandler
+    def initialize(handling_option)
+      @handling_option = handling_option
+    end
+
+    # Handles nil when evaling the attribute
+    # @param attribute [String] Name of the attribute
+    # @return [String] Code string to handle a nil attribute according to the handling option
+    def in_attribute_eval(attribute)
+      select_handling(
+        attribute,
+        include: ->(attrib) { "(self['#{attrib}'] || 0)" }
+      )
+    end
+
+    # Handles nil for an array of values for the attribute
+    # @param array [Array] Array of integers representing values of the attribute
+    # @return [Array] Array of integers representing values of the attribute, now corrected for nil values
+    def in_array(array)
+      select_handling(
+        array,
+        include: ->(arr) { arr << nil }
+      )
+    end
+
+    private
+
+    def select_handling(value, handling_actions)
+      action = handling_actions[@handling_option] || handling_actions[:include]
+
+      action.call(value)
+    end
+  end
+end

data/lib/bitmask_enum/options.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module BitmaskEnum
+  NIL_HANDLING_OPTIONS = [:include].freeze
+
+  # Handles the bitmask enum's user-provided options
+  # @api private
+  class Options
+    attr_reader :flag_prefix, :flag_suffix, :nil_handling, :validate
+
+    def initialize(options)
+      @nil_handling = options[:nil_handling].to_sym
+      unless NIL_HANDLING_OPTIONS.include?(@nil_handling)
+        raise BitmaskEnumInvalidError, "#{@nil_handling} is not a valid nil handling option"
+      end
+
+      @flag_prefix = options[:flag_prefix].nil? ? '' : "#{options[:flag_prefix]}_"
+      @flag_suffix = options[:flag_suffix].nil? ? '' : "_#{options[:flag_suffix]}"
+      @validate = options[:validate]
+    end
+  end
+end

data/lib/bitmask_enum/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module BitmaskEnum
+  VERSION = '1.0.0'
+end

data/lib/bitmask_enum.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'active_record'
+require 'bitmask_enum/attribute'
+require 'bitmask_enum/errors'
+
+# Adds support for bitmask enum attributes to ActiveRecord models.
+module BitmaskEnum
+  DEFAULT_BITMASK_ENUM_OPTIONS = {
+    flag_prefix: nil,
+    flag_suffix: nil,
+    nil_handling: :include,
+    validate: true
+  }.freeze
+
+  # Defines a bitmask enum and constructs the magic methods and method overrides for handling it.
+  # @param params [Hash] Hash with first key/value being the attribute name and an array of flags,
+  #   the remaining keys being options.
+  #   - `flag_prefix`: Symbol or string that prefixes all the created method names for flags joined with an underscore
+  #   - `flag_suffix`: Symbol or string that suffixes all the created method names for flags joined with an underscore
+  #   - `nil_handling`: Symbol or string signaling behaviour when handling nil attribute values. Options are:
+  #     - `include`: Treat nil as 0 and include in queries, this is the default.
+  #   - `validate`: Boolean to apply attribute validation. Attributes will validate that they are
+  #     less than the number of flags squared (number of flags squared - 1 is the highest valid bitmask value).
+  #     Defaults to `true`.
+  def bitmask_enum(params)
+    validation_error = validate_params(params)
+    raise BitmaskEnumInvalidError, validation_error if validation_error.present?
+
+    attribute, flags = params.shift
+    flags = flags.map(&:to_sym)
+    options = params
+    merged_options = DEFAULT_BITMASK_ENUM_OPTIONS.merge(options.symbolize_keys)
+
+    Attribute.new(self, attribute, flags, merged_options, defined_bitmask_enum_methods).construct!
+  end
+
+  private
+
+  def validate_params(params)
+    return 'must be a hash' unless params.is_a?(Hash)
+    return 'attribute must be a symbol or string and cannot be empty' unless text?(params.first.first)
+
+    flags = params.first[1]
+    return if flags.is_a?(Array) && flags.all? { |f| text?(f) }
+
+    'must provide a symbol or string array of flags'
+  end
+
+  def text?(value)
+    (value.is_a?(Symbol) || value.is_a?(String)) && value.size.positive?
+  end
+
+  def defined_bitmask_enum_methods
+    @defined_bitmask_enum_methods ||= {}
+  end
+end
+
+ActiveRecord::Base.extend(BitmaskEnum)

data/pre-commit

@@ -0,0 +1,19 @@
+#!/bin/sh
+
+
+rake spec
+
+valid=$?
+
+if [[ $valid -ne 0 ]]; then
+  exit $valid
+fi
+
+for file in $(git diff-index --name-only --diff-filter AM --cached HEAD); do
+  if (echo $file | egrep -q '(\.rb|Gemfile|Rakefile|\.gemspec)$') then
+    bundle exec rubocop --force-exclusion $file
+    valid=$(( $valid == 0 ? $? : $valid ))
+  fi
+done
+
+exit $valid

metadata

@@ -0,0 +1,174 @@
+--- !ruby/object:Gem::Specification
+name: bitmask_enum
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Lucy Gilbert
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-08-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+    - - "<="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+    - - "<="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.35'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.35'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.12'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description:
+email:
+- lucygilbert01@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".travis.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/setup
+- bitmask_enum.gemspec
+- lib/bitmask_enum.rb
+- lib/bitmask_enum/attribute.rb
+- lib/bitmask_enum/conflict_checker.rb
+- lib/bitmask_enum/errors.rb
+- lib/bitmask_enum/eval_scripts.rb
+- lib/bitmask_enum/nil_handler.rb
+- lib/bitmask_enum/options.rb
+- lib/bitmask_enum/version.rb
+- pre-commit
+homepage: https://github.com/lucygilbert/bitmask_enum
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org/
+  homepage_uri: https://github.com/lucygilbert/bitmask_enum
+  source_code_uri: https://github.com/lucygilbert/bitmask_enum
+  changelog_uri: https://github.com/lucygilbert/bitmask_enum/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key:
+specification_version: 4
+summary: A bitmask enum attribute for ActiveRecord
+test_files: []