swifter_enum 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4faeac3f2e6714d5af882726817712536924044c725a0aa252de4f0e89072f43
+  data.tar.gz: 5c818c9815c9e4e5165475260ffd42b503b815ca7eb92307ea98a703b8c2a933
+SHA512:
+  metadata.gz: 813389dc72d261ac9aa903484829009f8853ce4a0e6c017f8529996f2816858bdd13b4e5294f10b6a1c6dd93d3c1341e5c4e9a651f6b14712bf8fdddf49255a9
+  data.tar.gz: 39941760574f2ac9438ab61537273ed593e0a813200169dcdb68f863251992b8973aada7f3b094ef0aeb6182e7f87fe5bd30d61303bbd643e5bb0313a7f0e1c5

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 2.6

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-01-22
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Rob Jonson
+
+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,269 @@
+# SwifterEnum
+
+SwifterEnum is a Ruby gem for creating enumerated types (enums) in Ruby on Rails applications. 
+It is inspired by Swift's enums, and allows for more expressive and feature-rich enums in your models.
+
+Rather than simply having a key/value, enums are Classes, and can have defined methods.
+
+so - after defining
+
+    class Video < ApplicationRecord
+      swifter_enum :camera, CameraEnum
+    end
+
+you can then define and access methods on your enum like
+
+`video.camera.icon`
+or `video.camera.default_exposure`
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'swifter_enum'
+
+And then execute:
+
+    bundle install
+
+## Usage
+
+### Overview
+
+
+SwifterEnums act like a normal Rails enum - except that instead of returning symbol values, they return an instance of your selected class
+
+We have a Video ActiveModel with an enum defined by
+
+    class Video < ApplicationRecord
+      swifter_enum :camera, CameraEnum
+    end
+
+CameraEnum is a class like the following
+
+    class CameraEnum < SwifterEnum::Base
+      def self.values
+        { videographer: 0, handcam: 1 }.freeze
+      end
+
+      def icon
+        case @value
+        when :videographer
+          "icons/video-camera"
+        when :handcam
+          "icons/hand-stop"
+        end
+      end
+    end
+
+This provides a richer approach to enums:
+
+    v = Video.first
+    v.camera => #<CameraEnum:0x0000000134c7c290 @value=:handcam> 
+    v.camera.value => :handcam 
+
+    #you can set values directly
+    v.camera = :videographer
+    v.camera => #<CameraEnum:0x000000013385f078 @value=:videographer> 
+
+    #the purpose of this gem is that you can now define and access methods on the CameraEnum
+    v.camera.icon => "icons/video-camera" 
+
+
+### Using Enums in ActiveRecord Models
+
+To use an enum in an ActiveRecord model, use the `swifter_enum` class method provided by the gem in exactly the same way that you would normally use `enum`
+
+Example:
+
+    class Video < ApplicationRecord
+      swifter_enum :camera, CameraEnum
+
+      #optional validation
+      validates :camera, swifter_enum: true
+    end
+
+Models are by convention stored in `/models/swifter_enum/your_model_enum.rb`
+
+
+### Enum Class 
+
+Example:
+
+    class CameraEnum < SwifterEnum::Base
+      def self.values
+        { videographer: 0, handcam: 1 }.freeze
+      end
+
+      def icon
+        case @value
+        when :videographer
+          "icons/video-camera"
+        when :handcam
+          "icons/hand-stop"
+        end
+      end
+    end
+
+The only requirements for your enum class are
+
+* Inherit from SwifterEnum::Base
+* Define self.values which returns a hash of `{symbol: Integer}`
+
+You can then add whatever methods are useful to you.
+
+### Migrating an existing enum
+
+let's say you have an existing enum
+
+    enum :album_status, {
+      waiting_for_footage: 0,
+      waiting_for_upload: 10,
+      uploading: 20,
+      processing_preview: 24,
+      delivered_preview: 26,
+      processing_paid: 30,
+      delivered_paid: 50,
+      processing_failed: 60
+    }, prefix: true
+
+run the generator to create an appropriate enum class
+
+`rails g swifter_enum:enum AlbumStatus`
+
+Insert the values of your enum into `models/swifter_enum_album_status_enum.rb`
+
+    class AlbumStatusEnum < SwifterEnum::Base
+      def self.values
+        {
+          waiting_for_footage: 0,
+          waiting_for_upload: 10,
+          uploading: 20,
+          processing_preview: 24,
+          delivered_preview: 26,
+          processing_paid: 30,
+          delivered_paid: 50,
+          processing_failed: 60
+        }.freeze
+      end
+    end
+
+Now replace the definition in your model file with
+
+    swifter_enum :album_status, AlbumStatusEnum, prefix: true
+
+Optionally, add
+
+    validates :album_status, swifter_enum: true
+
+Run your tests and fix any issues. 
+
+The main change is where you were assuming that your enum would return a string value. 
+
+Typically, in my code, I would convert these to a symbol before comparing. So, I have to remove `album_status.to_sym` calls.
+
+Now I can use `album_status.value` to get a symbol value, 
+
+    album_status.value => :uploading
+
+or if I'm doing a comparison - I can just use `album_status`.
+
+    if album_status == :uploading {} #works as expected
+    if album_status == 'uploading' {} #also works as expected
+
+
+Now I'm ready to use my enum class by defining new methods.
+
+For example
+
+    class AlbumStatusEnum < SwifterEnum::Base
+
+      #values set as above
+
+      def delivered?
+        [:delivered_paid, :delivered_preview].include? self.value
+      end
+
+    end
+
+which allows me to use `model.album_status.delivered?`
+
+
+### Generator Usage
+
+SwifterEnum provides a Rails generator to easily create new enum classes. To generate an enum, use the following command:
+
+    rails g swifter_enum:enum [EnumName]
+
+Replace `[EnumName]` with the desired name for your enum. This will create a new enum file in the `app/models` directory.
+
+For example, to create a `CameraEnum`, run:
+
+    rails g swifter_enum:enum Camera
+
+This command will generate a file `app/models/swifter_enum/camera_enum.rb` with the following structure:
+
+    class CameraEnum < SwifterEnum::Base
+      def self.values
+        # Insert your values here. e.g. { foo: 1, bar: 2 }.freeze
+        { }.freeze
+      end
+    end
+
+After generating your enum, you can add your specific enum values and use it in your ActiveRecord models.
+
+### Translation and Display
+
+SwifterEnum supports i18n out of the box. Define translations in your locale files, and use the `.t` method on your enum instances to get the translated string.
+
+Locale file example (`config/locales/en.yml`):
+
+    en:
+      swifter_enum:
+        enums:
+          camera_enum:
+            videographer: "Videographer"
+            handcam: "Handheld Camera"
+
+    #example usage
+    v.camera.t => "Videographer"
+
+### Raw Value Escape Hatch
+
+SwifterEnum is built on top of the normal Rails enum functionality.
+
+If you're using a framework that needs to access this (Like Administrate), then you can use the `[name]_raw` method
+
+This also provides the keys method for select forms, so form builders should work (though the label will be `[name]_raw` rather than `[name]`)
+
+So, if you define Video.camera as a CameraEnum, then Video.camera_raw returns the standard Rails enum which lies beneath.
+
+Example:
+
+    v.camera  => #<CameraEnum:0x000000013385f078 @value=:videographer> 
+
+    # Accessing the raw value
+    v.camera_raw  => "videographer" 
+
+    # Setting the raw value
+    v.camera_raw = "handcam" #or =:handcam
+    v.camera =  => #<CameraEnum:0x000000016f7223e0 @value=:handcam> 
+
+    v.camera_raw = 0
+    v.camera =  => #<CameraEnum:0x000000016f7223e0 @value=:videographer> 
+
+    # Getting the mapping
+    Video.camera_raws # => { videographer: 0, handcam: 1 }
+
+so, for my Administrate dashboard, I would use
+
+    album_status_raw: Field::Select.with_options(searchable: false, collection: ->(field) { field.resource.class.send(field.attribute.to_s.pluralize).keys }),
+
+## More Info
+
+See the tests folder for more examples of usage.
+
+## Contributing
+
+Bug reports and pull requests are welcome

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+require "bundler/gem_tasks"
+require "standard/rake"
+
+# run rake standard:fix to standardise
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+task default: [:standard, :test]

data/lib/swifter_enum/base.rb

@@ -0,0 +1,33 @@
+module SwifterEnum
+  class Base
+    attr_reader :value
+
+    def self.values
+      {}
+    end
+
+    def initialize(value)
+      @value = value&.to_sym
+    end
+
+    def ==(other)
+      if other.is_a?(Symbol) || other.is_a?(String)
+        value.to_s == other.to_s
+      else
+        other.instance_of?(self.class) && value == other.value
+      end
+    end
+
+    def t
+      I18n.t("swifter_enum.#{self.class.name.demodulize.underscore}.#{@value}")
+    end
+
+    def to_s
+      @value
+    end
+
+    def self.all
+      values.keys.map { |value| new(value) }
+    end
+  end
+end

data/lib/swifter_enum/generators/enum/enum_generator.rb

@@ -0,0 +1,13 @@
+require "rails/generators/base"
+
+module SwifterEnum
+  module Generators
+    class EnumGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      def create_enum_file
+        template "enum.rb.tt", File.join("app/models/swifter_enum", class_path, "#{file_name}_enum.rb")
+      end
+    end
+  end
+end

data/lib/swifter_enum/generators/enum/templates/enum.rb.tt

@@ -0,0 +1,19 @@
+# Add this to your ActiveRecord model with:
+# swifter_enum :<%= file_name %>, <%= class_name %>Enum
+
+class <%= class_name %>Enum < SwifterEnum::Base
+
+  def self.values
+    # Insert your values here as you would for a normal enum
+    # { foo: 1, bar: 2 }.freeze
+
+    { }.freeze
+  end
+
+  # you can now define methods on the enum
+  # this would allow you to access YourModel.<%= file_name %>.squared
+  #def squared
+  # @value * @value
+  #end
+
+end

data/lib/swifter_enum/railtie.rb

@@ -0,0 +1,15 @@
+module SwifterEnum
+  class Railtie < Rails::Railtie
+    # ActiveRecord integration
+    initializer "swifter_enum.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        include SwifterEnum
+      end
+    end
+
+    # adding autoload paths
+    initializer "swifter_enum.add_autoload_paths", before: :set_autoload_paths do |app|
+      app.config.autoload_paths += Dir[Rails.root.join("app", "models", "swifter_enum")]
+    end
+  end
+end

data/lib/swifter_enum/swifter_enum.rb

@@ -0,0 +1,49 @@
+require "active_support/concern"
+
+module SwifterEnum
+  extend ActiveSupport::Concern
+
+  class_methods do
+    def swifter_enum(enum_name, enum_klass, enum_options = {})
+      # Define the enum using values from the enum class
+      enum(enum_name => enum_klass.values, **enum_options)
+
+      # Define getter method
+      define_method(enum_name) do
+        enum_klass.new(read_attribute(enum_name))
+      end
+
+      # Define setter method
+      define_method(:"#{enum_name}=") do |new_value|
+        if new_value.is_a?(enum_klass)
+          super(new_value.value)
+        else
+          super(new_value)
+        end
+      end
+
+      # Raw setter/getter allow escape valve for e.g. administrate
+      # So, if your swifter_enum is
+      # swifter_enum :camera, CameraKind
+      # you can get and set camera_raw with standard enum values
+      # and you can get the mapping with YourClass.camera_raws
+      # This allows you to use andminstrate as an example on camera_raw and expect form selects to work normally.
+
+      # Define raw getter method
+      define_method(:"#{enum_name}_raw") do
+        read_attribute(enum_name)
+      end
+
+      # Define raw setter method
+      define_method(:"#{enum_name}_raw=") do |new_value|
+        write_attribute(enum_name, new_value)
+      end
+
+      # Define class method to fetch the keys
+      # Rails returns string keys, so copy that
+      define_singleton_method(:"#{enum_name}_raws") do
+        enum_klass.values.transform_keys(&:to_s)
+      end
+    end
+  end
+end

data/lib/swifter_enum/swifter_enum_validator.rb

@@ -0,0 +1,17 @@
+require "active_model"
+
+module SwifterEnum
+  class SwifterEnumValidator < ActiveModel::EachValidator
+    def validate_each(record, attribute, a_value)
+      return if options[:allow_nil] && a_value.nil?
+
+      if !a_value.is_a?(SwifterEnum::Base) || a_value.instance_of?(SwifterEnum::Base)
+        record.errors.add(attribute, "#{a_value.value} is not a valid subclass of SwifterEnum")
+      end
+
+      unless a_value.class.values.key?(a_value.value)
+        record.errors.add(attribute, "#{a_value.value} is not a valid #{attribute} type")
+      end
+    end
+  end
+end

data/lib/swifter_enum/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SwifterEnum
+  VERSION = "0.9.0"
+end

data/lib/swifter_enum.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "swifter_enum/base"
+require "swifter_enum/swifter_enum"
+require "swifter_enum/swifter_enum_validator"
+require "swifter_enum/railtie" if defined?(Rails)
+
+if defined?(Rails::Generators) && Rails.env.development?
+  require "swifter_enum/generators/enum/enum_generator"
+end

data/sig/swifter_enum.rbs

@@ -0,0 +1,4 @@
+module SwifterEnum
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/swifter_enum.gemspec

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "lib/swifter_enum/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "swifter_enum"
+  spec.version = SwifterEnum::VERSION
+  spec.authors = ["Rob Jonson"]
+  spec.email = ["rob@hobbyistsoftware.com"]
+
+  spec.summary = "Active Record enum that uses a class, so you can add methods."
+  spec.description = "Simple enum for active record that takes inspiration from Swift's enums to allow you to add logic to your enum definition. This is easy to drop-in as a replacement for regular rails enums, with minimal changes required. Once you switch, then you can easily extend your enums with methods."
+  spec.homepage = "https://github.com/ConfusedVorlon/SwifterEnum"
+  spec.license = "MIT"
+
+  #I'm using 3.2 and above. If you're willing/able to test on lower rubies, then please let me know and feel free to change this.
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/ConfusedVorlon/SwifterEnum"
+  spec.metadata["changelog_uri"] = "https://github.com/ConfusedVorlon/SwifterEnum"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activerecord", "~> 7.0"
+  spec.add_dependency "activesupport", "~> 7.0"
+  spec.add_dependency "activemodel", "~> 7.0"
+
+  # Specify development dependencies
+  spec.add_development_dependency "sqlite3", "~> 1.4" # For using SQL
+  spec.add_development_dependency "minitest", "~> 5.22"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

metadata

@@ -0,0 +1,134 @@
+--- !ruby/object:Gem::Specification
+name: swifter_enum
+version: !ruby/object:Gem::Version
+  version: 0.9.0
+platform: ruby
+authors:
+- Rob Jonson
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-03-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !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'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.22'
+description: Simple enum for active record that takes inspiration from Swift's enums
+  to allow you to add logic to your enum definition. This is easy to drop-in as a
+  replacement for regular rails enums, with minimal changes required. Once you switch,
+  then you can easily extend your enums with methods.
+email:
+- rob@hobbyistsoftware.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".standard.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/swifter_enum.rb
+- lib/swifter_enum/base.rb
+- lib/swifter_enum/generators/enum/enum_generator.rb
+- lib/swifter_enum/generators/enum/templates/enum.rb.tt
+- lib/swifter_enum/railtie.rb
+- lib/swifter_enum/swifter_enum.rb
+- lib/swifter_enum/swifter_enum_validator.rb
+- lib/swifter_enum/version.rb
+- sig/swifter_enum.rbs
+- swifter_enum.gemspec
+homepage: https://github.com/ConfusedVorlon/SwifterEnum
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ConfusedVorlon/SwifterEnum
+  source_code_uri: https://github.com/ConfusedVorlon/SwifterEnum
+  changelog_uri: https://github.com/ConfusedVorlon/SwifterEnum
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.6
+signing_key:
+specification_version: 4
+summary: Active Record enum that uses a class, so you can add methods.
+test_files: []