enumancer 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 84c1bea1a7dd401a30ccc5688a86cfba9829a7cfceb58c5bb60b4124bbbacea2
+  data.tar.gz: ec380b6ec4a8d8b219995676508d02572b78ab40eb0080838cb14fded29a7048
+SHA512:
+  metadata.gz: 7505cd08d8b118be3dac15c7e29b9b2b1372e93858b1889972e8112d0f6bb33e1246d874cd4423c2fab210f3c71e736455169f57deaa1e2fa391fe7418cc5fff
+  data.tar.gz: 5c290f4da876dd4edab3ded6760aa4ee1ccbe7243dbd13fdcae161872b9d72eb49381e8289f229abcaa78978050be0679de1639738fd0fd796f372b050299887

data/lib/enum.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+# Enumancer::Enum provides a declarative, type-safe registry for named values.
+# Each entry is unique by both name and value. Values can be of any type,
+# but you may optionally declare a type constraint using `type`.
+# If type is defined, values are strictly checked.
+#
+# Enum entries are registered via `.entry(name, value)` and accessed via `.name` or `[]`.
+# Each entry becomes a singleton method of the class and returns an instance of the enum.
+#
+# You may enable strict mode via `type Klass, strict: true`, which disables fallbacks
+# and raises errors when accessing unknown names or values.
+#
+# @example Define an enum
+#   class MyEnum < Enumancer::Enum
+#     type Integer, strict: true
+#     entry :low, 1
+#     entry :high, 2
+#   end
+#
+# @example Access values
+#   MyEnum[:low].value         # => 1
+#   MyEnum.high.to_sym         # => :low
+#   MyEnum.low == MyEnum[:low] # => true
+#
+# @example Serialize to JSON
+#   MyEnum.low.to_json         # => '{"name":"low","value":1}'
+#
+# @example Deserialize from JSON
+#   MyEnum.from_json('{"name":"low"}') # => MyEnum.low
+
+require 'json'
+
+module Enumancer
+  class Enum
+    attr_reader :value
+
+    def initialize(value)
+      @value = value
+    end
+
+    # Returns the symbolic name of the value as a string
+    #
+    # @return [String]
+    def to_s
+      to_sym.to_s
+    end
+
+    # Returns the symbolic name of the value as a symbol
+    #
+    # @return [Symbol]
+    def to_sym
+      name = self.class.name_for(value)
+      raise KeyError, "Unregistered enum value: #{value.inspect}" if name.nil? && self.class.strict?
+      name || :unknown
+    end
+
+    # Returns a debug-friendly string representation
+    #
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} #{to_sym.inspect}:#{value.inspect}>"
+    end
+
+    # Equality based on class and value
+    #
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(self.class) && other.value == value
+    end
+
+    alias eql? ==
+    def hash = value.hash
+
+    # Serializes the enum to JSON
+    #
+    # @return [String]
+    def to_json(*args)
+      { name: to_sym, value: value }.to_json(*args)
+    end
+
+    class << self
+      # Called when subclassing Enum
+      #
+      # @param subclass [Class]
+      # @return [void]
+      def inherited(subclass)
+        subclass.instance_variable_set(:@registry, {})
+        subclass.instance_variable_set(:@values, {})
+        subclass.instance_variable_set(:@strict_mode, false)
+      end
+
+      # Declares the expected type of all enum values
+      #
+      # @param klass [Class] the type constraint for values
+      # @param strict [Boolean] whether to enable strict mode
+      # @return [void]
+      def type(klass, strict: false)
+        unless klass.is_a?(Class)
+          raise ArgumentError, "Expected a Class, got #{klass.inspect}"
+        end
+        @value_type = klass
+        @strict_mode = strict
+      end
+
+      # Returns whether strict mode is enabled
+      #
+      # @return [Boolean]
+      def strict?
+        @strict_mode == true
+      end
+
+      # Registers a new enum entry with a unique name and value
+      #
+      # @param name [Symbol, String] symbolic name of the entry
+      # @param value [Object] value of the entry
+      # @raise [ArgumentError] if name or value is already registered
+      # @raise [TypeError] if value does not match declared type
+      # @return [void]
+      def entry(name, value)
+        name = name.to_sym
+
+        if defined?(@value_type) && !value.is_a?(@value_type)
+          raise TypeError, "Invalid value type for #{name}: expected #{@value_type}, got #{value.class}"
+        end
+
+        if @values.key?(value)
+          existing = @values[value]
+          raise ArgumentError, "Duplicate value #{value.inspect} for #{name}; already assigned to #{existing}"
+        end
+
+        if @registry.key?(name)
+          raise ArgumentError, "Duplicate name #{name}; already registered with value #{@registry[name].value.inspect}"
+        end
+
+        instance = new(value)
+        @registry[name] = instance
+        @values[value] = name
+
+        define_singleton_method(name) { instance }
+      end
+
+      # Retrieves an enum instance by name
+      #
+      # @param name [Symbol, String]
+      # @return [Enumancer::Enum, nil]
+      def [](name)
+        @registry[name.to_sym]
+      end
+
+      # Retrieves an enum instance by name, raising if not found
+      #
+      # @param name [Symbol, String]
+      # @return [Enumancer::Enum]
+      # @raise [KeyError]
+      def fetch(name)
+        @registry.fetch(name.to_sym)
+      end
+
+      # Resolves the symbolic name for a given value
+      #
+      # @param value [Object]
+      # @return [Symbol, nil]
+      def name_for(value)
+        @values[value]
+      end
+
+      # Returns all registered enum instances
+      #
+      # @return [Array<Enumancer::Enum>]
+      def all
+        @registry.values
+      end
+
+      # Returns all registered names
+      #
+      # @return [Array<Symbol>]
+      def keys
+        @registry.keys
+      end
+
+      # Returns all raw values
+      #
+      # @return [Array<Object>]
+      def values
+        @registry.values.map(&:value)
+      end
+
+      # Removes an enum entry by name
+      #
+      # @param name [Symbol, String]
+      # @return [Enumancer::Enum, nil] the removed entry or nil
+      def remove(name)
+        name = name.to_sym
+        entry = @registry.delete(name)
+        if entry
+          @values.delete(entry.value)
+          singleton_class.undef_method(name) if respond_to?(name)
+        end
+        entry
+      end
+
+      # Deserializes an enum from JSON
+      #
+      # @param json [String]
+      # @return [Enumancer::Enum, nil]
+      # @raise [KeyError] if strict and name is unknown
+      def from_json(json)
+        data = JSON.parse(json, symbolize_names: true)
+        name = data[:name]
+        raise KeyError, "Missing 'name' key in JSON" if name.nil?
+
+        entry = self[name]
+        if strict? && entry.nil?
+          raise KeyError, "Unregistered enum name: #{name.inspect}"
+        end
+        entry
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,45 @@
+--- !ruby/object:Gem::Specification
+name: enumancer
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Łasačka
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |2
+      Enumancer provides a predictable, type-safe registry for named values.
+      Each entry is unique by both name and value, with optional type constraints and strict mode.
+email: saikinmirai@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/enum.rb
+homepage: https://github.com/lasaczka/enumancer
+licenses:
+- BSD-3-Clause-Attribution
+metadata:
+  changelog_uri: https://github.com/lasaczka/enumancer/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/lasaczka/enumancer/issues
+  documentation_uri: https://rubydoc.info/gems/kolor/1.0.0
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.8.0.dev
+specification_version: 4
+summary: Easy to use typed enums.
+test_files: []