value_semantics 3.5.0 → 3.6.0

data/lib/value_semantics/anything.rb

@@ -0,0 +1,11 @@
+module ValueSemantics
+  #
+  # Validator that matches any and all values
+  #
+  module Anything
+    # @return [true]
+    def self.===(_)
+      true
+    end
+  end
+end

data/lib/value_semantics/array_coercer.rb

@@ -0,0 +1,23 @@
+module ValueSemantics
+  class ArrayCoercer
+    attr_reader :element_coercer
+
+    def initialize(element_coercer = nil)
+      @element_coercer = element_coercer
+      freeze
+    end
+
+    def call(obj)
+      if obj.respond_to?(:to_a)
+        array = obj.to_a
+        if element_coercer
+          array.map { |element| element_coercer.call(element) }
+        else
+          array
+        end
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/value_semantics/array_of.rb

@@ -0,0 +1,18 @@
+module ValueSemantics
+  #
+  # Validator that matches arrays if each element matches a given subvalidator
+  #
+  class ArrayOf
+    attr_reader :element_validator
+
+    def initialize(element_validator)
+      @element_validator = element_validator
+      freeze
+    end
+
+    # @return [Boolean]
+    def ===(value)
+      Array === value && value.all? { |element| element_validator === element }
+    end
+  end
+end

data/lib/value_semantics/attribute.rb

@@ -0,0 +1,100 @@
+module ValueSemantics
+  #
+  # Represents a single attribute of a value class
+  #
+  class Attribute
+    NOT_SPECIFIED = Object.new.freeze
+    NO_DEFAULT_GENERATOR = lambda do
+      raise NoDefaultValue, "Attribute does not have a default value"
+    end
+
+    attr_reader :name, :validator, :coercer, :default_generator,
+      :instance_variable, :optional
+    alias_method :optional?, :optional
+
+    def initialize(
+      name:,
+      default_generator: NO_DEFAULT_GENERATOR,
+      validator: Anything,
+      coercer: nil
+    )
+      @name = name.to_sym
+      @default_generator = default_generator
+      @validator = validator
+      @coercer = coercer
+      @instance_variable = '@' + name.to_s.chomp('!').chomp('?')
+      @optional = !default_generator.equal?(NO_DEFAULT_GENERATOR)
+      freeze
+    end
+
+    def self.define(
+      name,
+      validator=Anything,
+      default: NOT_SPECIFIED,
+      default_generator: nil,
+      coerce: nil
+    )
+      # TODO: change how defaults are specified:
+      #
+      #  - default: either a value, or a callable
+      #  - default_value: always a value
+      #  - default_generator: always a callable
+      #
+      # This would not be a backwards compatible change.
+      generator = begin
+        if default_generator && !default.equal?(NOT_SPECIFIED)
+          raise ArgumentError, "Attribute `#{name}` can not have both a `:default` and a `:default_generator`"
+        elsif default_generator
+          default_generator
+        elsif !default.equal?(NOT_SPECIFIED)
+          ->{ default }
+        else
+          NO_DEFAULT_GENERATOR
+        end
+      end
+
+      new(
+        name: name,
+        validator: validator,
+        default_generator: generator,
+        coercer: coerce,
+      )
+    end
+
+    # @deprecated Use a combination of the other instance methods instead
+    def determine_from!(attr_hash, value_class)
+      raw_value = attr_hash.fetch(name) do
+        if default_generator.equal?(NO_DEFAULT_GENERATOR)
+          raise MissingAttributes, "Attribute `#{value_class}\##{name}` has no value"
+        else
+          default_generator.call
+        end
+      end
+
+      coerced_value = coerce(raw_value, value_class)
+      if validate?(coerced_value)
+        [name, coerced_value]
+      else
+        raise InvalidValue, "Attribute `#{value_class}\##{name}` is invalid: #{coerced_value.inspect}"
+      end
+    end
+
+    def coerce(attr_value, value_class)
+      return attr_value unless coercer # coercion not enabled
+
+      if coercer.equal?(true)
+        value_class.public_send(coercion_method, attr_value)
+      else
+        coercer.call(attr_value)
+      end
+    end
+
+    def validate?(value)
+      validator === value
+    end
+
+    def coercion_method
+      "coerce_#{name}"
+    end
+  end
+end

data/lib/value_semantics/bool.rb

@@ -0,0 +1,11 @@
+module ValueSemantics
+  #
+  # Validator that only matches `true` and `false`
+  #
+  module Bool
+    # @return [Boolean]
+    def self.===(value)
+      true.equal?(value) || false.equal?(value)
+    end
+  end
+end

data/lib/value_semantics/class_methods.rb

@@ -0,0 +1,34 @@
+module ValueSemantics
+  #
+  # All the class methods available on ValueSemantics classes
+  #
+  # When a ValueSemantics module is included into a class,
+  # the class is extended by this module.
+  #
+  module ClassMethods
+    #
+    # @return [Recipe] the recipe used to build the ValueSemantics module that
+    #                  was included into this class.
+    #
+    def value_semantics
+      if block_given?
+        # caller is trying to use the monkey-patched Class method
+        raise "`#{self}` has already included ValueSemantics"
+      end
+
+      self::VALUE_SEMANTICS_RECIPE__
+    end
+
+    #
+    # A coercer object for the value class
+    #
+    # This is mostly useful when nesting value objects inside each other.
+    #
+    # @return [#call] A callable object that can be used as a coercer
+    # @see ValueObjectCoercer
+    #
+    def coercer
+      ValueObjectCoercer.new(self)
+    end
+  end
+end

data/lib/value_semantics/dsl.rb

@@ -0,0 +1,106 @@
+module ValueSemantics
+  #
+  # Builds a {Recipe} via DSL methods
+  #
+  # DSL blocks are <code>instance_eval</code>d against an object of this class.
+  #
+  # @see Recipe
+  # @see ValueSemantics.for_attributes
+  #
+  class DSL
+    #
+    # Builds a {Recipe} from a DSL block
+    #
+    # @yield to the block containing the DSL
+    # @return [Recipe]
+    def self.run(&block)
+      dsl = new
+      dsl.instance_eval(&block)
+      Recipe.new(attributes: dsl.__attributes.freeze)
+    end
+
+    attr_reader :__attributes
+
+    def initialize
+      @__attributes = []
+    end
+
+    def Bool
+      Bool
+    end
+
+    def Either(*subvalidators)
+      Either.new(subvalidators)
+    end
+
+    def Anything
+      Anything
+    end
+
+    def ArrayOf(element_validator)
+      ArrayOf.new(element_validator)
+    end
+
+    def HashOf(key_validator_to_value_validator)
+      unless key_validator_to_value_validator.size.equal?(1)
+        raise ArgumentError, "HashOf() takes a hash with one key and one value"
+      end
+
+      HashOf.new(
+        key_validator_to_value_validator.keys.first,
+        key_validator_to_value_validator.values.first,
+      )
+    end
+
+    def RangeOf(subvalidator)
+      RangeOf.new(subvalidator)
+    end
+
+    def ArrayCoercer(element_coercer)
+      ArrayCoercer.new(element_coercer)
+    end
+
+    IDENTITY_COERCER = :itself.to_proc
+    def HashCoercer(keys: IDENTITY_COERCER, values: IDENTITY_COERCER)
+      HashCoercer.new(key_coercer: keys, value_coercer: values)
+    end
+
+    #
+    # Defines one attribute.
+    #
+    # This is the method that gets called under the hood, when defining
+    # attributes the typical +#method_missing+ way.
+    #
+    # You can use this method directly if your attribute name results in invalid
+    # Ruby syntax. For example, if you want an attribute named +then+, you
+    # can do:
+    #
+    #     include ValueSemantics.for_attributes {
+    #       # Does not work:
+    #       then String, default: "whatever"
+    #       #=> SyntaxError: syntax error, unexpected `then'
+    #
+    #       # Works:
+    #       def_attr :then, String, default: "whatever"
+    #     }
+    #
+    #
+    def def_attr(*args, **kwargs)
+      __attributes << Attribute.define(*args, **kwargs)
+      nil
+    end
+
+    def method_missing(name, *args, **kwargs)
+      if respond_to_missing?(name)
+        def_attr(name, *args, **kwargs)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, _include_private=nil)
+      first_letter = method_name.to_s.each_char.first
+      first_letter.eql?(first_letter.downcase)
+    end
+  end
+end

data/lib/value_semantics/either.rb

@@ -0,0 +1,18 @@
+module ValueSemantics
+  #
+  # Validator that matches if any of the given subvalidators matches
+  #
+  class Either
+    attr_reader :subvalidators
+
+    def initialize(subvalidators)
+      @subvalidators = subvalidators
+      freeze
+    end
+
+    # @return [Boolean]
+    def ===(value)
+      subvalidators.any? { |sv| sv === value }
+    end
+  end
+end

data/lib/value_semantics/hash_coercer.rb

@@ -0,0 +1,30 @@
+module ValueSemantics
+  class HashCoercer
+    attr_reader :key_coercer, :value_coercer
+
+    def initialize(key_coercer:, value_coercer:)
+      @key_coercer, @value_coercer = key_coercer, value_coercer
+      freeze
+    end
+
+    def call(obj)
+      hash = coerce_to_hash(obj)
+      return obj unless hash
+
+      {}.tap do |result|
+        hash.each do |key, value|
+          r_key = key_coercer.(key)
+          r_value = value_coercer.(value)
+          result[r_key] = r_value
+        end
+      end
+    end
+
+    private
+
+      def coerce_to_hash(obj)
+        return nil unless obj.respond_to?(:to_h)
+        obj.to_h
+      end
+  end
+end

data/lib/value_semantics/hash_of.rb

@@ -0,0 +1,20 @@
+module ValueSemantics
+  #
+  # Validator that matches +Hash+es with homogeneous keys and values
+  #
+  class HashOf
+    attr_reader :key_validator, :value_validator
+
+    def initialize(key_validator, value_validator)
+      @key_validator, @value_validator = key_validator, value_validator
+      freeze
+    end
+
+    # @return [Boolean]
+    def ===(value)
+      Hash === value && value.all? do |key, value|
+        key_validator === key && value_validator === value
+      end
+    end
+  end
+end

data/lib/value_semantics/instance_methods.rb

@@ -0,0 +1,170 @@
+module ValueSemantics
+  #
+  # All the instance methods available on ValueSemantics objects
+  #
+  module InstanceMethods
+    #
+    # Creates a value object based on a hash of attributes
+    #
+    # @param attributes [#to_h] A hash of attribute values by name. Typically a
+    #   +Hash+, but can be any object that responds to +#to_h+.
+    #
+    # @raise [UnrecognizedAttributes] if given_attrs contains keys that are not
+    #   attributes
+    # @raise [MissingAttributes] if given_attrs is missing any attributes that
+    #   do not have defaults
+    # @raise [InvalidValue] if any attribute values do no pass their validators
+    # @raise [TypeError] if the argument does not respond to +#to_h+
+    #
+    def initialize(attributes = nil)
+      attributes_hash =
+        if attributes.respond_to?(:to_h)
+          attributes.to_h
+        else
+          raise TypeError, <<-END_MESSAGE.strip.gsub(/\s+/, ' ')
+            Can not initialize a `#{self.class}` with a `#{attributes.class}`
+            object. This argument is typically a `Hash` of attributes, but can
+            be any object that responds to `#to_h`.
+          END_MESSAGE
+        end
+
+      remaining_attrs = attributes_hash.keys
+      missing_attrs = nil
+      invalid_attrs = nil
+
+      self.class.value_semantics.attributes.each do |attr|
+        if remaining_attrs.delete(attr.name)
+          value = attributes_hash.fetch(attr.name)
+        elsif attr.optional?
+          value = attr.default_generator.()
+        else
+          missing_attrs ||= []
+          missing_attrs << attr.name
+          next
+        end
+
+        coerced_value = attr.coerce(value, self.class)
+        if attr.validate?(coerced_value)
+          instance_variable_set(attr.instance_variable, coerced_value)
+        else
+          invalid_attrs ||= {}
+          invalid_attrs[attr.name] = coerced_value
+        end
+      end
+
+      # TODO: aggregate all exceptions raised from #initialize into one big
+      # exception that explains everything that went wrong, instead of multiple
+      # smaller exceptions. Unfortunately, this would not be backwards
+      # compatible.
+      unless remaining_attrs.empty?
+        raise UnrecognizedAttributes.new(
+          "`#{self.class}` does not define attributes: " +
+            remaining_attrs.map { |k| '`' + k.inspect + '`' }.join(', ')
+        )
+      end
+
+      if missing_attrs
+        raise MissingAttributes.new(
+          "Some attributes required by `#{self.class}` are missing: " +
+            missing_attrs.map { |a| "`#{a}`" }.join(', ')
+        )
+      end
+
+      if invalid_attrs
+        raise InvalidValue.new(
+          "Some attributes of `#{self.class}` are invalid:\n" +
+            invalid_attrs.map { |k,v| "  - #{k}: #{v.inspect}" }.join("\n") +
+            "\n"
+        )
+      end
+    end
+
+    #
+    # Returns the value for the given attribute name
+    #
+    # @param attr_name [Symbol] The name of the attribute. Can not be a +String+.
+    # @return The value of the attribute
+    #
+    # @raise [UnrecognizedAttributes] if the attribute does not exist
+    #
+    def [](attr_name)
+      attr = self.class.value_semantics.attributes.find do |attr|
+        attr.name.equal?(attr_name)
+      end
+
+      if attr
+        public_send(attr_name)
+      else
+        raise UnrecognizedAttributes, "`#{self.class}` has no attribute named `#{attr_name.inspect}`"
+      end
+    end
+
+    #
+    # Creates a copy of this object, with the given attributes changed (non-destructive update)
+    #
+    # @param new_attrs [Hash] the attributes to change
+    # @return A new object, with the attribute changes applied
+    #
+    def with(new_attrs)
+      self.class.new(to_h.merge(new_attrs))
+    end
+
+    #
+    # @return [Hash] all of the attributes
+    #
+    def to_h
+      self.class.value_semantics.attributes
+        .map { |attr| [attr.name, public_send(attr.name)] }
+        .to_h
+    end
+
+    #
+    # Loose equality
+    #
+    # @return [Boolean] whether all attributes are equal, and the object
+    #                   classes are ancestors of eachother in any way
+    #
+    def ==(other)
+      (other.is_a?(self.class) || is_a?(other.class)) && other.to_h.eql?(to_h)
+    end
+
+    #
+    # Strict equality
+    #
+    # @return [Boolean] whether all attribuets are equal, and both objects
+    #                   has the exact same class
+    #
+    def eql?(other)
+      other.class.equal?(self.class) && other.to_h.eql?(to_h)
+    end
+
+    #
+    # Unique-ish integer, based on attributes and class of the object
+    #
+    def hash
+      to_h.hash ^ self.class.hash
+    end
+
+    def inspect
+      attrs = to_h
+        .map { |key, value| "#{key}=#{value.inspect}" }
+        .join(" ")
+
+      "#<#{self.class} #{attrs}>"
+    end
+
+    def pretty_print(pp)
+      pp.object_group(self) do
+        to_h.each do |attr, value|
+          pp.breakable
+          pp.text("#{attr}=")
+          pp.pp(value)
+        end
+      end
+    end
+
+    def deconstruct_keys(_)
+      to_h
+    end
+  end
+end