type 0.1.0

data/lib/type/definition.rb

@@ -0,0 +1,165 @@
+# encoding: utf-8
+
+require 'type/definition/proxy'
+
+module Type
+  # Type::Definition is the interface for all type definitions.
+  #
+  # Standard implementations are:
+  #   - Type::Definition::Scalar
+  #   - Type::Definition::Collection
+  # Modifier implementations are:
+  #   - Type::Definition::Nilable, available as Type::Definition#nilable
+  #
+  module Definition
+    module ClassMethods
+      # @api protected
+      #   Public APIs are Type::scalar and Type::collection
+      # @overload generate(name, &block)
+      #   The block is called in the context of the definition, and is expected
+      #   to call one of `#validate` or `#cast` with appropriate blocks.
+      #   @param name [Symbol, nil] (nil)
+      #     Capital-letter symbol (e.g., `:Int32`) for which to register this
+      #     definition globally.
+      #   @return [Type::Definition]
+      #   @example
+      #   ~~~ ruby
+      #     Type::scalar(:Integer) do
+      #       validate do |input|
+      #         input.kind_of?(::Integer)
+      #       end
+      #       cast do |input|
+      #         Kernel::Integer(input)
+      #       end
+      #     end
+      #   ~~~
+      #
+      # @overload generate(name)
+      #   @param name [Symbol, nil] (nil)
+      #     Capital-letter symbol (e.g., `:Int32`) for which to register this
+      #     definition globally.
+      #   @return [Type::Definition::Proxy]
+      #     You are expected to call from(type_def, &block) to finish the
+      #     definition
+      # @return [Type::Definition, Type::Definition::Proxy]
+      #   @example
+      #   ~~~ ruby
+      #     Type::scalar(:Int32).from(:Integer) do
+      #       int32_range = (-1 << 31) ... (1 << 31)
+      #       validate do |input|
+      #         int32_range.include?(input)
+      #       end
+      #     end
+      #   ~~~
+      def generate(name = nil, &block)
+        return new(name, &block) if block_given?
+        Proxy.new(name, self)
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Create a new Type::Definition
+    #   You should never have to use Type::Definition#initialize directly;
+    #   instead use Type::Definition::generate()
+    #
+    # @param name [Symbol] (nil)
+    #   Capital-letter symbol (e.g., `:Int32`) for which to register this
+    #   definition globally.
+    #   If defining a `Type::Definition` with name `:FooBar`,
+    #   the following are registerde:
+    #     - `Type::FooBar`: a reference to the `Type::Definition`
+    #     - `Type::FooBar()`: an alias to `Type::FooBar::cast!()`
+    #     - `Type::FooBar?()`: an alias to `Type::FooBar::validate?()`
+    # @param parent [Symbol, Type::Definition]
+    #   A parent Type::Definition whose validation and casting is done *before*
+    #   it is done in self. See the builtin Type::Int32 for an example.
+    def initialize(name = nil, parent = nil, &block)
+      @name = name && name.to_sym
+      if parent
+        @parent = Type.find(parent)
+        validators.concat @parent.validators.dup
+        castors.concat @parent.castors.dup
+      end
+      Type.register(self)
+      instance_exec(&block) if block_given?
+    end
+    attr_reader :name
+
+    # @param input [Object]
+    # @return [Boolean]
+    def valid?(input)
+      validators.all? { |proc| proc[input] }
+    rescue
+      false
+    end
+
+    # @param input [Object]
+    # @return [Object] the result of casting, guaranteed to be valid.
+    # @raise [Type::CastError]
+    def cast!(input)
+      input = yield if block_given?
+      raise CastError.new(input, self) if input.nil?
+      castors.reduce(input) do |intermediate, castor|
+        castor[intermediate]
+      end.tap do |output|
+        raise ValidationError.new(output, self) unless valid?(output)
+      end
+    rescue
+      raise CastError.new(input, self)
+    end
+    alias_method :[], :cast!
+
+    def refine(name = nil, &config)
+      self.class.new(name, self, &config)
+    end
+
+    # @return [Proc]
+    def to_proc
+      method(:cast!).to_proc
+    end
+
+    require 'type/definition/scalar'
+    require 'type/definition/collection'
+    require 'type/definition/nilable'
+
+    # @return [String]
+    def to_s
+      name ? "Type::#{name}" : super
+    end
+
+    # @api private
+    # @return [Array<Proc>]
+    # Allows seeding with parent's validators
+    def validators
+      (@validators ||= [])
+    end
+    protected :validators
+
+    # @api private
+    # @return [Array<Proc>]
+    # Allows seeding with parent's validators
+    def castors
+      (@castors ||= [])
+    end
+    protected :castors
+
+    # used for configuring, but not after set up.
+    # TODO: extract to DSL.
+    # @api private
+    def validate(&block)
+      validators << block
+    end
+    private :validate
+
+    # used for configuring, but not after set up.
+    # TODO: extract to DSL.
+    # @api private
+    def cast(&block)
+      castors << block
+    end
+    private :cast
+  end
+end

data/lib/type/definition/collection.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+
+require 'type/definition/collection/constrained'
+
+module Type
+  class << self
+    # see Definition::Collection#generate
+    def collection(name = nil, &block)
+      Definition::Collection.generate(name, &block)
+    end
+  end
+
+  module Definition
+    # Type::Definition::Collection validate and cast enumerables.
+    # For a more interesting implementation, see the constrained
+    # implementation of Type::Definition::Collection::Constrained
+    class Collection
+      include Definition
+
+      def valid?(input, &block)
+        return false unless input.kind_of?(Enumerable)
+        super
+      end
+
+      def cast!(input, &block)
+        raise CastError.new(input, self) unless input.kind_of?(Enumerable)
+        super
+      end
+    end
+  end
+end

data/lib/type/definition/collection/constrained.rb

@@ -0,0 +1,80 @@
+# encoding: utf-8
+
+module Type
+  module Definition
+    # Re-open Collection to add constraint methods
+    class Collection
+      # @overload constrain(constraint)
+      #   @param constraint [Type::Definition]
+      # @overload constrain(constraint)
+      #   @param constraint [Hash{Type::Defintion=>Type::Defintion}]
+      #     a single-element hash whose key is the constraint for keys,
+      #     and whose value is a constraint for values
+      # @return [Type::Defintion::Collection::Constrained]
+      def constrain(constraint)
+        Constrained.new(self, constraint)
+      end
+      alias_method :of, :constrain
+
+      # @return [False]
+      def constrained?
+        false
+      end
+
+      # A Constrained collection also validates and casts the contents
+      # of the collection.
+      class Constrained < Collection
+        # @api private (See Type::Defintion::Collection#constrain)
+        def initialize(parent, constraint)
+          @constraints = Array(constraint).flatten.map { |c| Type.find(c) }
+
+          validators  << method(:validate_each?)
+          castors     << method(:cast_each!)
+
+          super(nil, parent)
+
+          @name = "#{parent.name}(#{@constraints.join('=>')})"
+        end
+        attr_reader :constraints
+
+        # @return [True]
+        def constrained?
+          true
+        end
+
+        # @api private
+        def to_s
+          parent_name = @parent && @parent.name
+          return super unless parent_name
+          "Type::#{parent_name}(#{@constraints.join('=>')})"
+        end
+
+        protected
+
+        # @api private
+        # @param enum [Enumerable]
+        # @return [Boolean]
+        def validate_each?(enum)
+          enum.all? do |item|
+            next @constraints.first.valid?(item) if @constraints.size == 1
+            @constraints.zip(item).all? do |constraint, value|
+              constraint.valid?(value)
+            end
+          end
+        end
+
+        # @api private
+        # @param enum [Enumerable]
+        # @return [Enumerable]
+        def cast_each!(enum)
+          enum.map do |item|
+            next @constraints.first.cast!(item) if @constraints.size == 1
+            @constraints.zip(item).map do |constraint, value|
+              constraint.cast!(value)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/type/definition/nilable.rb

@@ -0,0 +1,55 @@
+# encoding: utf-8
+
+module Type
+  # Re-open Definition to add nilable methods
+  module Definition
+    # Return a nilable representation of this type definition
+    # @return [Type::Definition::Nilable]
+    def nilable
+      Nilable.new(self)
+    end
+
+    # @return [False]
+    def nilable?
+      false
+    end
+
+    # Nilable Type::Definitions are the same as their non-nilable
+    # counterparts with the following exceptions:
+    # - a `nil` value is considered valid
+    # - a `nil` value is returned without casting
+    class Nilable
+      include Definition
+      def initialize(parent)
+        super(nil, parent)
+      end
+
+      # Returns true if input is nil *or* the input is valid
+      def valid?(input)
+        input.nil? || super
+      end
+
+      # Casts the input unless it is nil
+      def cast!(input)
+        return nil if input.nil?
+        super
+      end
+
+      # @return [True]
+      def nilable?
+        true
+      end
+
+      # @return [self]
+      def nilable
+        self
+      end
+
+      # @return [String]
+      def to_s
+        parent_name = @parent && @parent.name
+        parent_name ? "Type::#{parent_name}(nilable)" : super
+      end
+    end
+  end
+end

data/lib/type/definition/proxy.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+
+module Type
+  module Definition
+    # @api private
+    # The Proxy is an in-progress definition, a convenience object to support
+    # the declaration syntax.
+    class Proxy
+      def initialize(name, klass)
+        @name = name
+        @klass = klass
+      end
+
+      # @see Type::Definition::generate() for usage
+      def from(parent, &config)
+        raise ArgumentError, 'Block Required!' unless block_given?
+
+        Type[parent].tap do |resolved_parent|
+          raise ArgumentError unless resolved_parent.kind_of?(@klass)
+        end.refine(@name, &config)
+      end
+    end
+  end
+end

data/lib/type/definition/scalar.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+
+module Type
+  class << self
+    # @see Definition::Scalar#generate
+    def scalar(name = nil, &block)
+      Definition::Scalar.generate(name, &block)
+    end
+  end
+
+  module Definition
+    # The Scalar Class is an implementation of Definition interface
+    # that takes 100% of implementation from the base. This is
+    # to differentiate it from Collection, which has additional
+    # constraints.
+    class Scalar
+      include Definition
+    end
+  end
+end

data/lib/type/error.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+
+module Type
+  # An Error class for exceptions raised while validating or casting
+  class Error < ::TypeError
+    def initialize(input, type_definition)
+      @input = input
+      @type_definition = type_definition
+      @cause = $! # aka $ERROR_INFO
+    end
+
+    def to_s
+      "<#{self.class.name}: #{message}#{caused_by_clause}>"
+    end
+
+    attr_reader :input, :type_definition, :cause
+
+    private
+
+    def caused_by_clause
+      return '' unless @cause
+      ", caused by #{@cause}"
+    end
+  end
+
+  # Type::CastError is the raised class of Type::Definition#cast!
+  class CastError < Error
+    def message
+      "Could not cast #{input.inspect} with #{type_definition}."
+    end
+  end
+
+  # Type::ValidationError is raised internally in Type::Definition#cast!
+  # when, after casting, an element fails to validate.
+  # @api private
+  class ValidationError < Error
+    def message
+      "#{input.inspect} is not valid #{type_definition}."
+    end
+  end
+end

data/lib/type/version.rb

@@ -0,0 +1,6 @@
+# encoding: utf-8
+
+module Type
+  # The Type gem is semantically versioned.
+  VERSION = '0.1.0'
+end

data/spec/type/builtin_spec.rb

@@ -0,0 +1,242 @@
+# encoding: utf-8
+require 'type'
+
+RSpec::Matchers.define(:cast) do |input|
+  match do |definition|
+    begin
+      @actual = definition.cast!(input)
+      if @chained
+        failure_message_for_should do
+          "Expected result to be #{@expected.inspect}(#{@expected.class}) " +
+          "but got #{@actual.inspect}(#{@actual.class}) instead"
+        end
+        @expected == @actual
+      else
+        true
+      end
+    rescue Type::CastError => cast_error
+      failure_message_for_should do
+        "#{definition} failed to cast #{input.inspect}(#{input.class}) " +
+        "by raising #{cast_error}(#{cast_error.cause})."
+      end
+      false
+    end
+  end
+
+  description do
+    "cast #{input.inspect}(#{input.class})"
+  end
+
+  chain(:to) do |expected|
+    description do
+      "cast #{input.inspect}(#{input.class}) to #{expected.inspect}(#{expected.class})"
+    end
+    @chained = true
+    @expected = expected
+  end
+
+  chain(:unchanged) do
+    description do
+      "cast #{input.inspect}(#{input.class}) unchanged"
+    end
+    @chained = true
+    @expected = input
+  end
+end
+
+RSpec::Matchers.define :validate do |input|
+  match do |definition|
+    definition.valid?(input)
+  end
+  description do
+    "validate #{input.inspect}(#{input.class})"
+  end
+end
+
+shared_examples_for 'Type::Definition::Nilable compatibility' do
+  context 'when nilable' do
+    subject { described_class.nilable }
+    it { should be_a_kind_of Type::Definition::Nilable }
+    it { should be_nilable }
+    it { should cast(nil).to(nil) }
+    it { should validate(nil) }
+    it { should_not cast(Object.new) unless described_class == Type::String }
+  end
+  it { should_not be_a_kind_of Type::Definition::Nilable }
+  it { should_not be_nilable }
+  it { should_not cast(nil) }
+  it { should_not validate(nil) }
+  it { should_not cast(Object.new) unless described_class == Type::String }
+end
+
+shared_examples_for 'Type::Definition::Scalar' do
+  include_examples 'Type::Definition::Nilable compatibility'
+  it { should be_a_kind_of Type::Definition }
+  it { should be_a_kind_of Type::Definition::Scalar }
+end
+
+shared_examples_for 'Type::Integer' do
+  it_should_behave_like 'Type::Definition::Scalar'
+
+  it { should cast(414).unchanged }
+  it { should cast('123').to(123) }
+  it { should cast(456).to(456) }
+  it { should cast(Math::PI).to(3) } # alabama ftw
+
+  it { should_not cast('not a number') }
+  it { should_not cast(Hash.new) }
+
+  it { should validate(123) }
+  it { should_not validate('123') }
+end
+
+shared_examples_for 'bounded Type::Integer' do
+  it_should_behave_like 'Type::Integer'
+
+  let(:range_max) { valid_range.end - (valid_range.exclude_end? ? 1 : 0) }
+  let(:range_min) { valid_range.begin }
+
+  it { should cast(range_max).unchanged }
+  it { should cast(range_min).unchanged }
+
+  it { should_not cast(range_max.next) }
+  it { should_not cast(range_min.pred) }
+
+  it { should validate(range_max) }
+  it { should_not validate(range_max.next) }
+end
+
+describe Type::Integer do
+  it_should_behave_like 'Type::Integer'
+end
+
+describe Type::Int32 do
+  let(:valid_range) { (-1 << 31)...(1 << 31) }
+  it_should_behave_like 'bounded Type::Integer'
+end
+
+describe Type::Int64 do
+  let(:valid_range) { (-1 << 63)...(1 << 63) }
+  it_should_behave_like 'bounded Type::Integer'
+end
+
+describe Type::UInt32 do
+  let(:valid_range) { 0...(1 << 32) }
+  it_should_behave_like 'bounded Type::Integer'
+end
+
+describe Type::UInt64 do
+  let(:valid_range) { 0...(1 << 64) }
+  it_should_behave_like 'bounded Type::Integer'
+end
+
+describe Type::Boolean do
+  it_should_behave_like 'Type::Definition::Scalar'
+  it { should validate true }
+  it { should validate false }
+  it { should_not validate nil }
+  it { should_not validate 'true' }
+  it { should_not validate 'false' }
+  it { should cast(true).unchanged }
+  it { should cast(false).unchanged }
+end
+
+shared_examples_for 'Type::Float' do
+  it_should_behave_like 'Type::Definition::Scalar'
+  it { should cast(10).to(10.0) }
+  it { should cast(12.3).unchanged }
+  it { should cast('12.3').to(12.3) }
+  it { should cast('123e-1').to(12.3) }
+  it { should cast('12.3e10').to(123000000000.0) }
+  it { should cast('123e10').to(1230000000000.0) }
+  it { should_not cast('a string') }
+  it { should_not cast(Hash.new) }
+  it { should validate(12.3) }
+  it { should_not validate(12) }
+end
+
+describe Type::Float do
+  include_examples 'Type::Float'
+  it { should validate(Float::INFINITY) }
+  it { should validate(-Float::INFINITY) }
+end
+
+describe Type::Float32 do
+  include_examples 'Type::Float'
+  it { should_not validate(Float::INFINITY) }
+  it { should_not validate(-Float::INFINITY) }
+end
+
+describe Type::Float64 do
+  include_examples 'Type::Float'
+  it { should_not validate(Float::INFINITY) }
+  it { should_not validate(-Float::INFINITY) }
+end
+
+describe Type::String do
+  its(:to_s) { should match(/Type::String/) }
+  it_should_behave_like 'Type::Definition::Scalar'
+  it { should cast(:abc).to('abc') }
+end
+
+describe Type::Array do
+  its(:to_s) { should match(/Type::Array/) }
+  it { should be_a_kind_of Type::Definition::Collection }
+  it { should validate(['asdf']) }
+  it { should cast(['foo']).unchanged }
+  it { should cast(['asdf', 1]).unchanged }
+end
+
+describe Type::Array.of(:String) do
+  its(:to_s) { should match(/Type::Array\(.*String.*\)/) }
+  it { should be_a_kind_of Type::Definition::Collection::Constrained }
+  it { should validate(['asdf']) }
+  it { should_not validate([nil, 'asdf']) }
+  it { should_not validate([:asdf]) }
+  it { should cast([:abc, 1]).to(['abc', '1']) }
+  it { should_not cast([nil, 1]) }
+end
+
+describe Type::Array.of(:String?) do
+  it { should be_a_kind_of Type::Definition::Collection::Constrained }
+  it { should validate(['asdf']) }
+  it { should validate([nil, 'asdf']) }
+  it { should_not validate([:asdf]) }
+  it { should cast([:abc, 1]).to(['abc', '1']) }
+  it { should cast([nil, 1]).to([nil, '1']) }
+end
+
+describe Type::Hash do
+  its(:to_s) { should match(/Type::Hash/) }
+  it { should cast([[1, 2], [3, 4]]).to(1 => 2, 3 => 4) }
+  it { should_not cast(17) }
+end
+
+describe Type::Hash.of(:String => :Integer) do
+  its(:to_s) { should match(/Type::Hash\(.*String.*Integer.*\)/) }
+  it { should be_a_kind_of Type::Definition::Collection::Constrained }
+  it { should validate('foo' => 12) }
+  it { should_not validate(foo: 12) }
+  it { should_not validate('foo' => '12') }
+  it { should cast('foo' => '12', :bar => 3).to('foo' => 12, 'bar' => 3) }
+  it { should cast('foo' => 12, 'bar' => 3).unchanged }
+  it { should cast([['12', 34], [56, '78']]).to('12' => 34, '56' => 78) }
+  it { should_not cast('foo' => 'foo') }
+end
+
+describe Type::Set do
+  it { should_not validate([123, 456]) }
+  it { should validate(Set.new([123, 456])) }
+  it { should_not validate(17) }
+  it { should cast([123, 456]).to(Set.new([123, 456])) }
+  it { should cast(Set.new([123, 456])).to(Set.new([123, 456])) }
+  it { should_not cast(17) }
+end
+
+describe Type::Set.of(:Integer) do
+  its(:to_s) { should match(/Type::Set(.*Integer.*)/) }
+  it { should validate(Set.new([1, 2, 3, 4])) }
+  it { should_not validate([1, 2, 3, 4]) }
+  it { should cast(Set.new([1, 2, 3, 4])).unchanged }
+  it { should cast([1, 2, 3, 4]).to(Set.new([1, 2, 3, 4])) }
+end