enumerize-schema 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 701e2767983ffcce7f84b2140eb664c7c9fc1c975d9a4b21f8c5b0c88fed026b
+  data.tar.gz: ca82797fd02bf1d7ff7885d74217741522522a4c9870887f83a26aa487e2be73
+SHA512:
+  metadata.gz: 95908592aa8dcb37fdc1888d68f5f0769ec56c74f64f87468a47aa1751cbf9af61d1fe0b01ee4b1deac718ae0ccebd21c31fae2d235f18c74f62dabefb934cdf
+  data.tar.gz: f048d1d8f31b0f12f7d689a4eaa4cff4d8ab6ed2cf6857e61b518a1e6f9d56a37690b5bda5d1dd9a5ee828d6e5486fe6be427927f43b776338d25ac7c0aedf87

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,2 @@
+parallel: true
+format: progress

data/.yardopts

@@ -0,0 +1 @@
+--no-private

data/CHANGELOG.md

@@ -0,0 +1,2 @@
+[Unreleased]
+------------

data/Gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "rspec-github", require: false

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Robert Audi
+
+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,72 @@
+Enumerize: Schema
+=================
+
+[![RSpec](https://github.com/RobertAudi/enumerize-schema/actions/workflows/rspec.yml/badge.svg)](https://github.com/RobertAudi/enumerize-schema/actions/workflows/rspec.yml)
+[![Standard](https://github.com/RobertAudi/enumerize-schema/actions/workflows/standard.yml/badge.svg)](https://github.com/RobertAudi/enumerize-schema/actions/workflows/standard.yml)
+
+Enumerize: Schema is wrapper around [Enumerize](https://github.com/brainspec/enumerize) that enables storing enum values in schema files.
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "enumerize-schema"
+```
+
+And then execute:
+
+```console
+$ bundle install
+```
+
+Usage
+-----
+
+Instead of using `extend Enumerize`, use `extend EnumerizeSchema` instead and define your enums with `attr_enum`:
+
+```ruby
+class User
+  extend EnumerizeSchema
+
+  attr_enum :role
+end
+```
+
+The values of the enum need to be listed in a YAML schema file. Here are the default paths for the schema file:
+
+- `config/enumerize.yml` in Ruby on Rails applications
+- `enumerize.yml` under `Bundler.root` (if Bundler is used) or the current working directory
+
+The structure of the schema file is similar to the one of I18n locale files:
+
+```yaml
+---
+user:
+  role:
+    - member
+    - moderator
+    - administrator
+```
+
+### Options
+
+Options are forwarded to `enumerize`. If the `:in` option is specified then `attr_enum` will not check the schema file and the `:in` option will also be forwarded to `enumerize`.
+
+Development
+-----------
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+Contributing
+------------
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/RobertAudi/enumerize-schema.
+
+License
+-------
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "standard/rake"
+require "yard"
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  if ENV["GITHUB_ACTIONS"]
+    t.rspec_opts = [
+      "--format RSpec::Github::Formatter",
+      "--format documentation",
+      "--force-color"
+    ]
+  end
+end
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = ["lib/**/*.rb"]
+end
+
+task default: [:standard, :spec]

data/bin/console

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "enumerize-schema"
+
+require "pry"
+Pry.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/enumerize-schema.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "lib/enumerize_schema/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "enumerize-schema"
+  spec.version = EnumerizeSchema::VERSION
+  spec.authors = ["Robert Audi"]
+  spec.email = ["robert@robertaudi.com"]
+
+  spec.summary = "Store Enumerize enum values in schema files"
+  spec.description = "A wrapper around Enumerize to store enum values in schema files"
+  spec.homepage = "https://github.com/RobertAudi/enumerize-schema"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/RobertAudi/enumerize-schema"
+  spec.metadata["changelog_uri"] = "#{spec.metadata["source_code_uri"]}/CHANGELOG.md"
+
+  # 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(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:spec/|\.git)})
+    end
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "enumerize", "~> 2.5.0"
+  spec.add_dependency "activesupport", ">= 3.2"
+
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "pry", "~> 0.14"
+  spec.add_development_dependency "rspec", "~> 3.2"
+  spec.add_development_dependency "standard", "~> 1.3"
+  spec.add_development_dependency "yard", "~> 0.9"
+end

data/lib/enumerize-schema.rb

@@ -0,0 +1 @@
+require_relative "./enumerize_schema"

data/lib/enumerize_schema/configuration.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module EnumerizeSchema
+  class Configuration
+    # @!attribute [r] default_config
+    #
+    # @return [Hash] the default config
+    def default_config
+      return @default_config if @default_config
+
+      config = {}
+
+      if defined?(Rails)
+        config[:schema_file] = Rails.root.join("config", "enumerize.yml")
+      else
+        root_path = Pathname.new(defined?(Bundler) ? Bundler.root : Dir.pwd)
+
+        config[:schema_file] = root_path.join("enumerize.yml")
+      end
+
+      @default_config = config.freeze
+    end
+
+    # @return [Pathname] the path to the schema file containing all the enum values
+    def schema_file
+      @schema_file ||= default_config[:schema_file]
+    end
+
+    # @param value [String, File, Pathname] the path to the schema file containing all the enum values
+    # @raise [SchemaFileNotFoundError] if +value+ is not a file
+    # @raise [SchemaFileNotReadableError] if +value+ is not a readable file
+    # @return [Pathname] the path to the schema file containing all the enum values
+    def schema_file=(value)
+      if !File.file?(value)
+        raise SchemaFileNotFoundError.new(schema_file: value)
+      elsif !File.readable?(value)
+        raise SchemaFileNotReadableError.new(schema_file: value)
+      else
+        @schema_file = Pathname.new(value)
+      end
+    end
+  end
+end

data/lib/enumerize_schema/errors.rb

@@ -0,0 +1,44 @@
+# @!group Errors
+module EnumerizeSchema
+  class SchemaFileNotFoundError < RuntimeError
+    # @return [String, nil] the schema file that caused the error
+    attr_reader :schema_file
+
+    # @param schema_file [String, nil] the schema file that caused the error
+    def initialize(schema_file:)
+      @schema_file = schema_file
+
+      super("Unable to locate the schema file: #{schema_file.inspect}")
+    end
+  end
+
+  class SchemaFileNotReadableError < RuntimeError
+    # @return [String, nil] the schema file that caused the error
+    attr_reader :schema_file
+
+    # @param schema_file [String, nil] the schema file that caused the error
+    def initialize(schema_file:)
+      @schema_file = schema_file
+
+      super("Unable to read the schema file #{schema_file.inspect}")
+    end
+  end
+
+  class MissingValuesError < KeyError
+    # @return [String] the name of the class where the enum is defined
+    attr_reader :class_name
+
+    # @return [String] the name of the enum attribute
+    attr_reader :attribute_name
+
+    # @param class_name [String] the name of the class where the enum is defined
+    # @param attribute_name [String] the name of the enum attribute
+    def initialize(class_name:, attribute_name:)
+      @class_name = class_name
+      @attribute_name = attribute_name
+
+      super("Enumerized values missing for attribute: #{class_name}##{attribute_name}")
+    end
+  end
+end
+# @!endgroup

data/lib/enumerize_schema/version.rb

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

data/lib/enumerize_schema.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "enumerize"
+require "active_support/inflector/methods"
+
+module EnumerizeSchema
+  autoload :Configuration, "enumerize_schema/configuration"
+  autoload :Version, "enumerize_schema/version"
+  require_relative "./enumerize_schema/errors"
+
+  # @!scope class
+
+  # @!attribute [r] config
+  # @return [Configuration] the EnumerizeSchema configuration object
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  # Configure EnumerizeSchema.
+  #
+  # @example
+  #   EnumerizeSchema.configure do |config|
+  #     config.schema_file = Rails.root.join("config", "enumerize", "schema.yml")
+  #   end
+  #
+  # @yieldparam config [Configuration] the EnumerizeSchema configuration object
+  def self.configure
+    yield(config)
+  end
+
+  # @private
+  def self.configured?
+    !!@__configured
+  end
+
+  # @private
+  def self.schema
+    @__schema ||=
+      if config.schema_file.to_s.empty?
+        {}
+      elsif !File.file?(config.schema_file)
+        raise SchemaFileNotFoundError.new(schema_file: config.schema_file)
+      elsif !File.readable?(config.schema_file)
+        raise SchemaFileNotReadableError.new(schema_file: config.schema_file)
+      else
+        YAML.load_file(config.schema_file) || {}
+      end
+  end
+
+  # @private
+  def self.extended(base)
+    unless base.singleton_class.ancestors.include?(Enumerize)
+      base.extend(Enumerize)
+    end
+
+    class << base
+      protected :attr_enum
+    end
+  end
+
+  # The path of the schema file for the specific class extended by EnumerizeSchema.
+  # This method will return +nil+ if a custom schema file was not specified.
+  #
+  # @example A class with a custom schema file
+  #   class User
+  #     extend EnumerizeSchema
+  #
+  #     self.enumerize_schema_file = Rails.root.join("config", "enumerize", "user.yml")
+  #   end
+  #
+  #   User.enumerize_schema_file
+  #   # => #<Pathname:config/enumerize/user.yml>
+  #
+  # @example Subsclasses inherit their parent's schema file
+  #   class User
+  #     extend EnumerizeSchema
+  #
+  #     self.enumerize_schema_file = Rails.root.join("config", "enumerize", "user.yml")
+  #   end
+  #
+  #   class Member < User
+  #   end
+  #
+  #   User.enumerize_schema_file
+  #   # => #<Pathname:config/enumerize/user.yml>
+  #   Member.enumerize_schema_file
+  #   # => #<Pathname:config/enumerize/user.yml>
+  #
+  # @example Subsclasses can also use their own schema file instead of their parent's
+  #   class User
+  #     extend EnumerizeSchema
+  #
+  #     self.enumerize_schema_file = Rails.root.join("config", "enumerize", "user.yml")
+  #   end
+  #
+  #   class Member < User
+  #     self.enumerize_schema_file = Rails.root.join("config", "enumerize", "member.yml")
+  #   end
+  #
+  #   User.enumerize_schema_file
+  #   # => #<Pathname:config/enumerize/user.yml>
+  #   Member.enumerize_schema_file
+  #   # => #<Pathname:config/enumerize/member.yml>
+  #
+  # @example Subsclasses can also use the default schema file instead of their parent's
+  #   class User
+  #     extend EnumerizeSchema
+  #
+  #     self.enumerize_schema_file = Rails.root.join("config", "enumerize", "user.yml")
+  #   end
+  #
+  #   class Member < User
+  #     self.enumerize_schema_file = nil
+  #   end
+  #
+  #   User.enumerize_schema_file
+  #   # => #<Pathname:config/enumerize/user.yml>
+  #   Member.enumerize_schema_file
+  #   # => nil
+  #
+  # @example A class without a custom schema file
+  #   class User
+  #     extend EnumerizeSchema
+  #   end
+  #
+  #   User.enumerize_schema_file
+  #   # => nil
+  #
+  def enumerize_schema_file
+    return @__enumerize_schema_file if instance_variable_defined?(:@__enumerize_schema_file)
+
+    @__enumerize_schema_file = superclass.instance_variable_get(:@__enumerize_schema_file)
+  end
+
+  # Override the path to the enumerized attribute schema file for the current class.
+  #
+  # @example
+  #   class User < ApplicationRecord
+  #     include EnumerizeSchema
+  #
+  #     self.enumerize_schema_file = Rails.root.join("config", "enumerize", "user.yml")
+  #   end
+  #
+  # @param value [String, File, Pathname] the path to the schema file containing all the enum values for the current class
+  # @raise [SchemaFileNotFoundError] if +value+ is not a file
+  # @raise [SchemaFileNotReadableError] if +value+ is not a readable file
+  # @return [Pathname] the path to the schema file containing all the enum values for the current class
+  def enumerize_schema_file=(value)
+    if value.to_s.empty?
+      @__enumerize_schema_file = nil
+    elsif !File.file?(value)
+      raise SchemaFileNotFoundError.new(schema_file: value)
+    elsif !File.readable?(value)
+      raise SchemaFileNotReadableError.new(schema_file: value)
+    else
+      @__enumerize_schema_file = Pathname.new(value)
+    end
+  end
+
+  # @api private
+  def enumerize_schema
+    @__enumerize_schema ||=
+      if enumerize_schema_file.to_s.empty?
+        ::EnumerizeSchema.schema
+      else
+        YAML.load_file(enumerize_schema_file) || {}
+      end
+  end
+
+  # @api private
+  def enumerize_schema_attributes_scope
+    @__enumerize_schema_attributes_scope ||= ActiveSupport::Inflector.underscore(name.to_s).split("/")
+  end
+
+  # Defines an enumerized attribute.
+  #
+  # @param attribute_name [Symbol] the name of the enumerized attribute
+  # @param enumerize_options [Hash] options forwarded to +enumerize+
+  # @raise [EnumerizeSchema::MissingValuesError] if the values for the enum are not found in the schema file
+  # @return [void]
+  #
+  # @note This method is marked as +protected+ when added to the class, so it can't be used from outside that class.
+  # @note If the +:in+ option is passed then this method will not check the schema file and forward all options to +enumerize+
+  # @see  https://github.com/brainspec/enumerize Enumerize
+  def attr_enum(attribute_name, **enumerize_options)
+    if enumerize_options.include?(:in)
+      enumerize(attribute_name, enumerize_options)
+    else
+      enum_values = Array(enumerize_schema.dig(*enumerize_schema_attributes_scope, attribute_name.to_s))
+
+      if enum_values.empty?
+        raise ::EnumerizeSchema::MissingValuesError.new(class_name: name, attribute_name: attribute_name)
+      end
+
+      enumerize(attribute_name, enumerize_options.merge(in: enum_values))
+    end
+  end
+end

metadata

@@ -0,0 +1,160 @@
+--- !ruby/object:Gem::Specification
+name: enumerize-schema
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Robert Audi
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-03-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: enumerize
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.5.0
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: A wrapper around Enumerize to store enum values in schema files
+email:
+- robert@robertaudi.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".standard.yml"
+- ".yardopts"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- enumerize-schema.gemspec
+- lib/enumerize-schema.rb
+- lib/enumerize_schema.rb
+- lib/enumerize_schema/configuration.rb
+- lib/enumerize_schema/errors.rb
+- lib/enumerize_schema/version.rb
+homepage: https://github.com/RobertAudi/enumerize-schema
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/RobertAudi/enumerize-schema
+  source_code_uri: https://github.com/RobertAudi/enumerize-schema
+  changelog_uri: https://github.com/RobertAudi/enumerize-schema/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.32
+signing_key:
+specification_version: 4
+summary: Store Enumerize enum values in schema files
+test_files: []