dux 0.3.0 → 0.8.0

data/lib/dux/blankness.rb

@@ -1,7 +1,14 @@
 module Dux
+  # `Object#blank?` and `Object#present?` replacements for when
+  # working outside of ActiveSupport.
+  #
+  # @api private
   module Blankness
+    # A string containing only whitespace (as defined by unicode).
     WHITESPACE_ONLY = /\A[[:space:]]+\z/
 
+    private_constant :WHITESPACE_ONLY
+
     # Check if a provided object is semantically empty.
     #
     # @param [Object] value
@@ -32,7 +39,7 @@ module Dux
     def presentish?(value)
       !blankish?(value)
     end
-
-    extend self
   end
+
+  extend Blankness
 end

data/lib/dux/comparable.rb

@@ -0,0 +1,241 @@
+module Dux
+  # Simplify the creation of comparable objects by specifying
+  # a list of attributes (with optional ordering) that
+  # determines how they should be compared, without having
+  # to define a spaceship (`<=>`) operator in the given class.
+  class Comparable < Module
+    # Valid orders for sorting
+    ORDERS = Dux.enum(:asc, :desc, aliases: { ascending: :asc, descending: :desc })
+
+    private_constant :ORDERS
+
+    # Checks if an attribute argument is a valid tuple
+    ATTRIBUTE_TUPLE = Dux.yard('(Symbol, Symbol)')
+
+    private_constant :ATTRIBUTE_TUPLE
+
+    # @param [<Symbol, (Symbol, Symbol)>] attributes
+    # @param [Boolean, String] type_guard
+    # @param [:asc, :desc, :ascending, :descending] sort_order
+    def initialize(*attributes, sort_order: :asc, type_guard: true, **options)
+      @default_sort_order = validate_order sort_order
+
+      @type_guard = validate_type_guard type_guard
+
+      @attributes = parse_attributes(attributes)
+
+      if @attributes.one?
+        @default_sort_order = @attributes.first.order
+      end
+
+      include ::Comparable
+
+      class_eval spaceship_method, __FILE__, __LINE__ + 1
+    end
+
+    # Display the attributes used to compare for clarity
+    # in class ancestor listings.
+    #
+    # @return [String]
+    def inspect
+      attribute_list = @attributes.map do |attribute|
+        attribute.to_inspect(many: many?, default: @default_sort_order)
+      end.join(', ')
+
+      if many?
+        attribute_list = "[#{attribute_list}]"
+
+        attribute_list << ", default_order: #{@default_sort_order.to_s.upcase}"
+      end
+
+      "Dux::Comparable(#{attribute_list})"
+    end
+
+    # Determine if we are operating on many attributes
+    #
+    # Boolean complement of {#single?}.
+    def many?
+      @attributes.length > 1
+    end
+
+    # Determine if we are operating on a single attribute
+    #
+    # Boolean complement of {#many?}.
+    def single?
+      @attributes.one?
+    end
+
+    # Determine if we have a type guard that requires
+    # another of the same class.
+    def same_type_guard?
+      @type_guard == true
+    end
+
+    # Determine if
+    def specific_type_guard?
+      @type_guard.kind_of?(String) && Dux.presentish?(@type_guard)
+    end
+
+    # Determine if we have any kind of type guard.
+    #
+    # @see [#same_type_guard?]
+    # @see [#specific_type_guard?]
+    def type_guard?
+      same_type_guard? || specific_type_guard?
+    end
+
+    # @api private
+    # @return [String]
+    def spaceship_method
+      @spaceship_method ||= build_spaceship_method
+    end
+
+    private
+
+    # Generates the spaceship method body.
+    #
+    # @return [String]
+    def build_spaceship_method
+      ''.tap do |body|
+
+        body << <<-RUBY
+          def <=>(other)
+        RUBY
+
+        if type_guard?
+          body << <<-RUBY
+              unless other.kind_of?(#{type_guard_value})
+                raise TypeError, "\#{other.inspect} must be kind of \#{#{type_guard_value}}"
+              end
+          RUBY
+        end
+
+        body << <<-RUBY
+            #{join_attributes}
+        RUBY
+
+        body << <<-RUBY
+          end
+        RUBY
+      end
+    end
+
+    # Join the attributes to be checked in {#build_spaceship_method}
+    #
+    # @see [Dux::Enum::Attribute#to_comparison]
+    # @return [String]
+    def join_attributes
+      @attributes.map do |attribute|
+        attribute.to_comparison(wrap: @attributes.length > 1)
+      end.join('.nonzero? || ')
+    end
+
+    # Provides the value for type guards used by {#build_spaceship_method}
+    # @return [String]
+    def type_guard_value
+      raise 'Cannot get value for non-type guard' unless type_guard?
+
+      if same_type_guard?
+        'self.class'
+      elsif specific_type_guard?
+        @type_guard
+      end
+    end
+
+    # @param [<Symbol, (Symbol, Symbol)>] attributes
+    # @return [<Dux::Enum::Attribute>]
+    def parse_attributes(attributes)
+      raise ArgumentError, "Must provide at least one attribute" if attributes.empty?
+
+      attributes.map do |attribute|
+        case attribute
+        when Symbol, String
+          Attribute.new(attribute, @default_sort_order)
+        when ATTRIBUTE_TUPLE
+          Attribute.new(attribute[0], validate_order(attribute[1]))
+        else
+          raise ArgumentError, "Don't know what to do with #{attribute.inspect}"
+        end
+      end.freeze
+    end
+
+    # @param [Symbol, String] sort_order
+    # @raise [ArgumentError] when given an improper sort order
+    # @return [Symbol]
+    def validate_order(sort_order)
+      ORDERS[sort_order]
+    rescue Dux::Enum::NotFound => e
+      raise ArgumentError, "invalid sort order: #{sort_order.inspect}"
+    end
+
+    # @param [Boolean, String, Symbol] type_guard
+    # @raise [TypeError] when given an improper type guard
+    # @return [Boolean, String, Symbol]
+    def validate_type_guard(type_guard)
+      case type_guard
+      when true, false, nil then type_guard
+      when Class, Module
+        type_guard.name
+      when String, Symbol, Dux::IndifferentString
+        type_guard.to_s
+      else
+        raise TypeError, "Don't know what to do with type guard: #{type_guard.inspect}"
+      end
+    end
+
+    # Attribute definition with sort ordering.
+    #
+    # @api private
+    class Attribute < Struct.new(:name, :order)
+      # Check if the {#order} is ascending
+      def ascending?
+        order == :asc
+      end
+
+      # Check if the {#order} is descending
+      def descending?
+        order == :desc
+      end
+
+      # @param [Boolean] many
+      # @param [:asc, :desc, nil] default
+      # @api private
+      # @return [String]
+      def to_inspect(many: false, default: nil)
+        ":#{name}".tap do |s|
+          s << " #{order.to_s.upcase}" unless many && order == default
+        end
+      end
+
+      # Generate the comparison expression used to compare
+      # this attribute against another.
+      #
+      # @param [Boolean] wrap if the expression should be wrapped
+      #   in parentheses.
+      # @return [String]
+      def to_comparison(wrap: false)
+        if ascending?
+          "self.#{name} <=> other.#{name}"
+        elsif descending?
+          "other.#{name} <=> self.#{name}"
+        end.tap do |expression|
+          return "(#{expression})" if wrap
+        end
+      end
+    end
+  end
+
+  class << self
+    # @!group DSL
+
+    # Create {Dux::Comparable a comparable module} with the provided options.
+    #
+    # @see [Dux::Comparable#initialize]
+    # @return [Dux::Comparable]
+    def comparable(*attributes, **options)
+      Dux::Comparable.new(*attributes, **options)
+    end
+
+    # @!endgroup
+  end
+end

data/lib/dux/duckify.rb

@@ -12,19 +12,7 @@ module Dux
     # @param [Boolean] include_all
     # @return [Proc]
     def duckify(include_all: false)
-      dux for_duckify, include_all: include_all
-    end
-
-    class << self
-      # @api private
-      # @param [Class] base
-      # @return [void]
-      def included(base)
-        base.__send__ :include, Dux
-      end
-
-      alias_method :prepended, :included
-      alias_method :extended, :included
+      Dux[for_duckify, include_all: include_all]
     end
   end
 end

data/lib/dux/enum.rb

@@ -10,22 +10,57 @@ module Dux
   class Enum
     include Enumerable
 
+    # {Dux::NullObject} to determine if we have no default value.
     NO_DEFAULT = Dux.null 'Dux::Enum::NO_DEFAULT', purpose: 'When no default has been provided'
 
     private_constant :NO_DEFAULT
 
-    def initialize(*values, default: NO_DEFAULT, allow_nil: false)
+    # Types that can be specified for a return type
+    RETURN_TYPES = %i[symbol string].freeze
+
+    private_constant :RETURN_TYPES
+
+    def initialize(*values, default: NO_DEFAULT, allow_nil: false, aliases: {}, return_type: :symbol)
       @allow_nil = allow_nil
 
+      set_return_type return_type
+
       set_values values
 
       set_default default
+
+      set_aliases aliases
+
+      freeze
+    end
+
+    # Test for inclusion with case equality
+    #
+    # @param [String, Symbol] other
+    def ===(other)
+      include? other
     end
 
+    # Check if the provided key is an alias.
+    #
+    # @param [Symbol, String] key
+    def alias?(key)
+      @aliases.key? key
+    end
+
+    # Check if we allow nil to be returned
+    # as a default / fallback.
+    def allow_nil?
+      @allow_nil
+    end
+
+    # Check if a default is set for this enum.
     def default?
       @default != NO_DEFAULT
     end
 
+    # @yield [value] each member of the enum
+    # @yieldparam [Dux::IndifferentString] value
     def each
       return enum_for(__method__) unless block_given?
 
@@ -34,9 +69,17 @@ module Dux
       end
     end
 
+    # @param [String, Symbol] value
+    # @param [String, Symbol] fallback
+    # @yield Executed in lieu of raising {Dux::Enum::NotFound} if there is an unknown member
+    # @raise [Dux::Enum::InvalidFallback] when provided with an invalid override fallback value
+    # @raise [Dux::Enum::NotFound] when fetching a value not found in the enum
+    # @return [Symbol]
     def fetch(value, fallback: NO_DEFAULT)
       if include? value
-        value
+        with_return_type value
+      elsif alias?(value)
+        with_return_type @aliases.fetch(value)
       elsif fallback != NO_DEFAULT
         if valid_fallback?(fallback)
           fallback
@@ -44,19 +87,20 @@ module Dux
           raise InvalidFallback, "Cannot use #{fallback.inspect} as a fallback"
         end
       elsif default?
-        @default
+        with_return_type @default
       else
-        raise NotFound, "Invalid enum member: #{value.inspect}"
+        if block_given?
+          yield value
+        else
+          raise NotFound, "Invalid enum member: #{value.inspect}"
+        end
       end
     end
 
     alias_method :[], :fetch
 
+    # @return [String]
     def inspect
-      inspection = [
-        @values.to_a.inspect
-      ]
-
       "Dux::Enum(#{@values.to_a.inspect})"
     end
 
@@ -65,21 +109,69 @@ module Dux
 
     private
 
+    # Ensure the value is returned with the correct type
+    # @param [String, Symbol, nil] value
+    # @return [String, Symbol, nil]
+    def with_return_type(value)
+      if value.nil? && allow_nil?
+        if allow_nil?
+          nil
+        else
+          # :nocov:
+          raise ArgumentError, "Cannot return `nil` without allow_nil: true"
+          # :nocov:
+        end
+      elsif @return_type == :symbol
+        value.to_sym
+      elsif @return_type == :string
+        value.to_s
+      end
+    end
+
+    # @param [Symbol] return_type
+    # @raise [ArgumentError] on improper return type
+    # @return [void]
+    def set_return_type(return_type)
+      if RETURN_TYPES.include? return_type
+        @return_type = return_type
+      else
+        raise ArgumentError, "Invalid return type: #{return_type.inspect}", caller
+      end
+    end
+
+    # @param [<String, Symbol>] values
+    # @raise [TypeError] if provided with no values
+    # @return [void]
     def set_values(values)
       raise TypeError, "Must provide some values", caller if values.empty?
 
       @values = values.flatten.map do |value|
         Dux::IndifferentString.new value
-      end.to_set
+      end.to_set.freeze
+    end
+
+    # @param [{Symbol => String, Symbol}] aliases
+    # @return [void]
+    def set_aliases(aliases)
+      raise TypeError, 'Aliases must be a hash' unless aliases.kind_of?(Hash)
+
+      @aliases = AliasMap.new *self, **aliases
     end
 
-    def valid_fallback?(fallback, default: false)
-      return true if fallback.nil? && @allow_nil
+    # Check if the provided `fallback` is valid
+    #
+    # @param [String, Symbol, nil] fallback
+    def valid_fallback?(fallback)
+      return true if fallback.nil? && allow_nil?
       return true if include? fallback
 
       false
     end
 
+    # Set the default fallback value.
+    #
+    # @param [String, Symbol, nil] fallback
+    # @return [void]
     def set_default(fallback)
       if valid_fallback?(fallback) || fallback == NO_DEFAULT
         @default = fallback
@@ -92,7 +184,98 @@ module Dux
     class NotFound < StandardError
     end
 
+    # Raised when attempting to use an invalid
+    # value as a fallback
     class InvalidFallback < ArgumentError
     end
+
+    # Raised when trying to set an already-defined
+    # member as an alias
+    class MemberAsAliasError < ArgumentError
+    end
+
+    # Raised when trying to set an invalid alias
+    # target
+    class InvalidAliasTargetError < ArgumentError
+    end
+
+    # An indifferent, read-only hash-like object
+    # for mapping aliases.
+    #
+    # @api private
+    class AliasMap
+      # @param [<Dux::IndifferentString>] targets
+      # @param [{Symbol => String, Symbol}] aliases
+      def initialize(*targets, **aliases)
+        @mapping = aliases.each_with_object({}) do |(aliaz, target), mapping|
+          aliaz   = indifferentize(aliaz)
+          target  = indifferentize(target)
+
+          if targets.include? aliaz
+            raise MemberAsAliasError, "alias `#{aliaz}` is already an enum member"
+          end
+
+          unless targets.include? target
+            raise InvalidAliasTargetError, "alias target `#{target}` is not an enum member"
+          end
+
+          mapping[aliaz] = target
+        end.freeze
+
+        @aliases = @mapping.keys.freeze
+
+        freeze
+      end
+
+      def alias?(aliaz)
+        @aliases.include? aliaz
+      end
+
+      alias_method :key?, :alias?
+
+      # @param [String, Symbol] aliaz
+      # @return [Dux::IndifferentString]
+      def fetch(aliaz)
+        @mapping[indifferentize(aliaz)]
+      end
+
+      alias_method :[], :fetch
+
+      # @return [Hash]
+      def to_h
+        # :nocov:
+        @mapping.to_h
+        # :nocov:
+      end
+
+      private
+
+      # Check if the value is acceptable for mapping.
+      def acceptable?(value)
+        value.kind_of?(String) || value.kind_of?(Symbol) || value.kind_of?(Dux::IndifferentString)
+      end
+
+      # @param [String, Symbol] value
+      # @return [Dux::IndifferentString]
+      def indifferentize(value)
+        raise TypeError, "invalid aliaz or target: #{value.inspect}" unless acceptable?(value)
+
+        Dux::IndifferentString.new value
+      end
+    end
+  end
+
+  class << self
+    # @!group DSL
+
+    # Create {Dux::Enum an enum} with the provided options.
+    #
+    # @see Dux::Enum#initialize
+    # @return [Dux::Enum]
+    def enum(*values, **options)
+      Dux::Enum.new(*values, **options)
+    end
+
+    # @!endgroup
   end
 end