enum-x 1.0.0

data/lib/enum_x/value.rb

@@ -0,0 +1,164 @@
+class EnumX
+
+  # One enum value. Each value has a name and may contain any format-specific values.
+  class Value
+
+    ######
+    # Initialization
+
+      # Initializes a new enum value.
+      #
+      # @param [EnumX] enum  The owning enum.
+      # @param [Hash|#to_s] value
+      #   The actual value. If a Hash is specified, it must contain a key 'value' or :value, and may
+      #   contain values for any other format. A format named :format is not allowed.
+      #
+      # == Examples
+      #   EnumX::Value.new(enum, 'new')
+      #   EnumX::Value.new(enum, {:value => 'new', :xml => '<new>'})
+      def initialize(enum, value)
+        raise ArgumentError, "enum required" unless enum
+        @enum  = enum
+
+        @formats = {}
+        case value
+        when Hash
+          process_hash(value)
+        else
+          @value = value.to_s
+        end
+      end
+
+      # Processes a value hash.
+      def process_hash(hash)
+        hash = hash.dup
+
+        value = hash.delete(:value) || hash.delete('value')
+        raise ArgumentError, "key :value is required when a hash value is specified" unless value
+
+        @value = value.to_s
+
+        # Process all other options as formats.
+        hash.each do |key, value|
+          raise ArgumentError, "key :format is not allowed" if key.to_s == 'format'
+          @formats[key.to_s] = value
+        end
+      end
+
+    ######
+    # Attributes
+
+      # @!attribute [r] enum
+      # @return [EnumX] The EnumX defining this value.
+      attr_reader :enum
+
+      # @!attribute [r] value
+      # @return [String] The actual string value.
+      attr_reader :value
+
+      # @!attribute [r] formats
+      # @return [Hash] Any other formats supported by this value.
+      attr_reader :formats
+
+      # @!attribute [r] symbol
+      # @return [Symbol] The value symbol.
+      def symbol
+        value.to_sym
+      end
+
+    ######
+    # Duplication
+
+      # Creates a duplicate of this enum value.
+      # @param [EnumX] enum  A new owner enum of the value.
+      # @return [EnumX::Value]
+      def dup(enum = self.enum)
+        Value.new(enum, @formats.merge(:value => value))
+      end
+
+    ######
+    # Value retrievers
+
+      alias :to_str :value
+      alias :to_s :value
+      alias :to_sym :symbol
+
+      # Pass numeric conversion to the string value.
+      def to_i; value.to_i end
+      def to_f; value.to_f end
+
+      def respond_to?(method)
+        if method =~ /^to_/ && !%w[ to_int to_a to_ary ].include?(method.to_s)
+          true
+        elsif method =~ /\?$/ && enum.values.include?($`)
+          true
+        else
+          super
+        end
+      end
+
+      def method_missing(method, *args, &block)
+        if method =~ /^to_/ && !%w[ to_int to_a to_ary ].include?(method.to_s)
+          @formats[$'] || value
+        elsif method =~ /\?$/
+          value = $`
+
+          if enum.values.include?(value)
+            # If the owning enum defines the requested value, we treat this as an mnmenonic. Test if this
+            # is the current value.
+            self == value
+          else
+            # If the owning enum does not define the requested value, we treat this as a missing method.
+            super
+          end
+        else
+          super
+        end
+      end
+      private :method_missing
+
+    ######
+    # I18n
+
+      def translate(options = {})
+        default_value = if defined?(ActiveSupport)
+          ActiveSupport::Inflector.humanize(to_s).downcase
+        else
+          to_s
+        end
+        I18n.translate value, options.merge(:scope => @enum.i18n_scope, :default => default_value)
+      end
+      def translate!(options = {})
+        I18n.translate value, options.merge(:scope => @enum.i18n_scope, :raise => true)
+      end
+
+    ######
+    # Common value object handling
+
+      def ==(other)
+        return false if other.nil?
+        value == other.to_s
+      end
+
+      def eql?(other)
+        return false if other.nil?
+        other.is_a?(EnumX::Value) && other.enum == enum && other.value == value
+      end
+
+      def hash
+        value.hash
+      end
+
+      def as_json(*args)
+        value
+      end
+
+      # EnumX values are simply stored as their string values.
+      def encode_with(coder)
+        coder.tag = nil
+        coder.scalar = value
+      end
+
+  end
+
+end

data/lib/enum_x/value_list.rb

@@ -0,0 +1,69 @@
+class EnumX
+
+  # A list of multiple enum values.
+  class ValueList
+
+    ######
+    # Initialization
+
+      def initialize(enum, values)
+        @enum = enum
+        values = [ values ] unless values.is_a?(Enumerable)
+        @values = values.map { |value| @enum[value] || value }
+      end
+
+    ######
+    # Attributes
+
+      attr_reader :enum
+
+      attr_reader :values
+
+    ######
+    # Method delegation
+
+      # Delegate everything to Array, except querying methods
+
+      # Obtains an array version of the enum.
+      alias :to_ary :values
+
+      # Converts the enum to an array of {EnumX::Value}s.
+      alias :to_a :values
+
+      # Creates a string representation of the values.
+      def to_s
+        values.map(&:to_s).join(', ')
+      end
+
+      include Enumerable
+
+      # Create delegate methods for all of Enumerable's own methods.
+      (Enumerable.instance_methods + [ :empty?, :present?, :blank? ]).each do |method|
+        class_eval <<-RUBY, __FILE__, __LINE__+1
+          def #{method}(*args, &block)
+            values.__send__ :#{method}, *args, &block
+          end
+        RUBY
+      end
+
+      def [](value)
+        values.find { |val| val.to_s == value.to_s }
+      end
+
+      def include?(value)
+        values.any? { |val| val.to_s == value.to_s }
+      end
+
+      def ==(other)
+        case other
+        when Array then values == other
+        when EnumX::ValueList then values == other.values
+        when EnumX::Value then values == [ other ]
+        else false
+        end
+      end
+
+
+  end
+
+end

data/lib/enum_x/version.rb

@@ -0,0 +1,3 @@
+class EnumX
+  VERSION = '1.0.0'
+end

data/lib/enum_x.rb

@@ -0,0 +1,336 @@
+require 'yaml'
+require 'json'
+require 'i18n'
+
+# Utility class representing an enumeration of options to choose from. This can be used
+# in models to make a field have a certain number of allowed options.
+#
+# Enums are defined in configuration files which are loaded from load paths (see {.load_paths}).
+#
+# == EnumX file format
+#
+# EnumX files are YAML files defining enumerations in the following format:
+#
+#   <name>: [ <value>, <value, ... ]
+#
+# E.g.
+#
+#   statuses: [ draft, sent, returned ]
+#
+# == Extra formats
+#
+# EnumX values are designed to be converted to various formats. By default, they simply support a name,
+# which is the value you specify in the YAML files. They also respond to any method starting with
+# 'to_', e.g. +to_string+, +to_json+, +to_legacy+. These return the name of the value, unless otherwise
+# specified explicitly when being defined.
+#
+# If you want to provide extra formats in the YAML, you may indicate them as follows:
+#
+#   statuses: [ { value: 'draft', legacy: 'new' }, sent, { value: 'returned', legacy: 'back' } ]
+#
+# Now, the following will all be true:
+#
+#   EnumX.statuses[:draft].value == 'draft'
+#   EnumX.statuses[:draft].symbol == :draft
+#   # => #symbol always returns the value converted to a Symbol
+#   EnumX.statuses[:draft].to_legacy == 'new'
+#   EnumX.statuses[:sent].value == 'sent'
+#   EnumX.statuses[:sent].symbol == :sent
+#   EnumX.statuses[:sent].to_legacy == 'sent'
+#   # => because no explicit value for the 'legacy' format was specified
+class EnumX
+
+  autoload :DSL, 'enum_x/dsl'
+  autoload :Value, 'enum_x/value'
+  autoload :ValueList, 'enum_x/value_list'
+
+  ######
+  # Registry class
+
+    # The enum registry. Provides indifferent access.
+    class Registry < Hash
+      def [](key)
+        super key.to_s
+      end
+    end
+
+  ######
+  # ValueHash class
+
+    # A hash for enum values. This is a regular Hash, except that it
+    # has completely indifferent access also integers are possible as keys.
+    class ValueHash < Hash
+      def [](key)
+        super key.to_s
+      end
+    end
+
+  ######
+  # EnumX retrieval
+
+    class << self
+
+      # An array of EnumX load paths.
+      #
+      # @example Add some enum load paths
+      #   EnumX.load_paths += Dir[ Rails.root + 'config/enums/**/*.yml' ]
+      def load_paths=(paths)
+        @load_paths = Array.wrap(paths)
+      end
+      def load_paths
+        @load_paths ||= []
+      end
+
+      # Defines a new enum with the given values.
+      # @see EnumX#initialize
+      def define(name, values)
+        registry[name.to_s] = new(name, values)
+      end
+
+      # Undefines an enum.
+      def undefine(name)
+        registry.delete name.to_s
+      end
+
+      # Retrieves an enum by name.
+      def [](name)
+        load_enums unless @registry
+        registry[name]
+      end
+
+      # Allows overriding of the load handler.
+      #
+      # Specify an object that responds to +load_enums_from(file, file_type)+ where +file+
+      # is a file name, and +file_type+ is either +:yaml+ or +:ruby+. Alternatively, a block
+      # may be specified that will receive these parameters.
+      #
+      # The method does not have to return anything, but should use calls to {define} to
+      # actually define the enums.
+      #
+      # By default, the loader parses the YAML file as a flat Hash, where the keys are enum
+      # names, and the values are arrays containing the values.
+      #
+      # == Usage
+      #
+      #   EnumX.loader = proc do |file, file_type|
+      #     if file_type == :ruby
+      #       load file
+      #     else
+      #       ... # Process the YAML file here.
+      #     end
+      #   end
+      attr_accessor :loader
+
+      private
+
+        # @!attribute [r] registry
+        # @return [Hash] All defined enums.
+        def registry
+          @registry ||= EnumX::Registry.new
+        end
+
+        # Tries to look for an enum by the given name.
+        #
+        #   EnumX.statuses == EnumX[:statuses]
+        def method_missing(method, *args, &block)
+          if enum = self[method]
+            enum
+          elsif method =~ /^to_/
+            super
+          else
+            raise NameError, "enum #{method} not found"
+          end
+        end
+
+        # Loads enums from the defined load paths.
+        def load_enums
+          load_paths.each do |path|
+            file_type = case path
+            when /\.rb$/ then :ruby
+            when /\.ya?ml$/ then :yaml
+            else :other
+            end
+
+            case loader
+            when Proc
+              loader.call(path, file_type)
+            when ->(l){ l.respond_to?(:load_enums_from) }
+              loader.load_enums_from(path, file_type)
+            else
+              case file_type
+              when :ruby
+                load path
+              when :yaml
+                load_enums_from_yaml(path)
+              else
+                # ignore the file
+              end
+            end
+          end
+        end
+
+        # Load enums from a YAML file.
+        def load_enums_from_yaml(file)
+          yaml = YAML.load_file(file)
+          yaml.each do |name, values|
+            define name, values
+          end
+        end
+
+    end
+
+  ######
+  # Initialization
+
+    # Initializes a new EnumX instance.
+    #
+    # @param [#to_s] name
+    #   The name of the enum. This is used to load translations. See {EnumX::Value#to_s}.
+    # @param [Enumerable] values
+    #   The values for the enumeration. Each item is passed to {EnumX::Value.new}.
+    def initialize(name, values)
+      @name = name.to_s
+
+      @values = ValueHash.new
+      values.each do |value|
+        add_value!(value)
+      end
+    end
+
+  ######
+  # Attributes
+
+    # @!attribute [r] name
+    # @return [String] The name of the enum.
+    attr_reader :name
+
+    # @!attribute [r] values
+    # @return [Array<EnumX::Value>] All allowed enum values.
+    def values
+      @values.values
+    end
+
+    # Make the enum enumerable. That's the least it should do!
+    include Enumerable
+
+    # Create delegate methods for all of Enumerable's own methods.
+    [ :each, :empty?, :present?, :blank? ].each do |method|
+      class_eval <<-RUBY, __FILE__, __LINE__+1
+        def #{method}(*args, &block)
+          values.__send__ :#{method}, *args, &block
+        end
+      RUBY
+    end
+
+    # Obtains a value by its key.
+    def [](key)
+      @values[key]
+    end
+
+    # Obtains an array version of the enum.
+    alias :to_ary :values
+
+    # Converts the enum to an array of {EnumX::Value}s.
+    alias :to_a :values
+
+  ######
+  # Operations
+
+    # Creates a duplicate of this enum.
+    def dup
+      EnumX.new(name, values)
+    end
+
+    # Creates a clone of this enumeration but without the given values.
+    def without(*values)
+      EnumX.new(name, self.values.reject{|v| values.include?(v)})
+    end
+
+    # Creates a duplicate of this enumeration but with only the given values.
+    def only(*values)
+      EnumX.new(name, self.values.select{|v| values.include?(v)})
+    end
+
+    # Adds the given values to the enum
+    def extend!(*values)
+      values.each { |value| add_value!(value) }
+    end
+
+  ######
+  # Translation
+
+    # The I18n scope for this enum. Override this to provide customization.
+    # Default: +enums.<name>+
+    def i18n_scope
+      [ :enums, name ]
+    end
+
+  ######
+  # Find method
+
+    # Finds an enum with the given name on a class.
+    # TODO: Spec
+    def self.find(klass, name)
+      return nil unless klass
+
+      enum = klass.send(name) if klass.respond_to?(name) rescue nil
+      enum if enum.is_a?(EnumX)
+    end
+
+  ######
+  # Value by <format>
+
+    # Finds an enum value by the given format.
+    #
+    # == Example
+    #
+    # Given the following enum:
+    #
+    #   @enum = EnumX.define(:my_enum,
+    #     { :value => 'one', :number => '1' },
+    #     { :value => 'two', :number => '2' }
+    #   )
+    #
+    # You can now access the values like such:
+    #
+    #   @enum.value_with_format(:number, '1') # => @enum[:one]
+    #   @enum.value_with_format(:number, '2') # => @enum[:two]
+    #
+    # Note that any undefined format for a value is defaulted to its value. Therefore, the following
+    # is also valid:
+    #
+    #   @enum.value_with_format(:unknown, 'one') # => @enum[:one]
+    #
+    # You can also access values by a specific format using the shortcut 'value_with_<format>':
+    #
+    #   @enum.value_with_number('1')    # => @enum[:one]
+    #   @enum.value_with_unknown('one') # => @enum[:one]
+    def value_with_format(format, search)
+      values.find { |val| val.send(:"to_#{format}") == search }
+    end
+
+  private
+
+    def method_missing(method, *args, &block)
+      if method =~ /^value_with_(.*)$/
+        raise ArgumentError, "`#{method}' accepts one argument, #{args.length} given" unless args.length == 1
+        value_with_format $1, args.first
+      else
+        super
+      end
+    end
+
+    # Add a new value to the enum values list
+    def add_value!(value)
+      value = case value
+        when Value then value.dup(self)
+        else Value.new(self, value)
+      end
+      @values[value.value] = value
+    end
+
+end
+
+# Extend Symbol & String with enum awareness.
+require 'enum_x/monkey'
+require 'enum_x/railtie' if defined?(Rails)