yard_types 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 722cc485964dc469732d1ef265f650bae6c029ee
+  data.tar.gz: 4e85d42f94b0d31a7991e076f62acdcc717c1c27
+SHA512:
+  metadata.gz: 154fb6a437ecd17d7c331836224e6706e4edb411f4de4dd3723fc98131f20b9487b5bfb4c6d33ad0bbd53c9f23577fdbc3bd44af58cea4c35c491b96737dc387
+  data.tar.gz: 11800a82a3a26ddc32c4472f086fa4ba20f53d9b98f8ebb03e2098d495b2cbef1c504142d4976c48d6f92b4c8731ba6095178ccb85cacbe8a899ff78acb0f173

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1
+  - ruby-head
+  - jruby
+  - rbx-2

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in yard_type_check.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Kyle Hargraves
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,63 @@
+# yard_types
+
+[![Build Status](https://travis-ci.org/pd/yard_types.svg?branch=master)](https://travis-ci.org/pd/yard_types)
+
+Parse YARD type description strings -- eg `Array<#to_sym>` -- and use the
+resulting types to check type correctness of objects at runtime.
+
+## Installation
+Like everything else these days:
+
+~~~ruby
+gem 'yard_types'
+~~~
+
+Note that the `yard` gem may automatically require anything named `yard_*` or
+`yard-*` on your load path, and attempt to use it as a plugin. You could see
+errors along the lines of `failed to load plugin yard_types`; this is harmless,
+as best I can tell.
+
+## Usage
+Parse a type description string, and test an object against it:
+
+~~~ruby
+type = YardTypes.parse('#quack') #=> #<YardTypes::TypeConstraint ...>
+
+type.check(Object.new)
+#=> false
+
+obj = Object.new
+def obj.quack; 'quack!'; end
+type.check(obj)
+#=> true
+~~~
+
+## Caveats
+YARD does not officially specify a syntax for its type descriptions; the syntax
+used by its own documentation varies between files. The syntax supported in
+this gem aims to follow the rules given by the [YARD Type Parser][type-parser].
+
+In the wild, people seem to use a wide variety of different syntaxes, many of
+which are unlikely to be supported right now. If you find any such examples,
+feel free to file an issue -- or better yet, write a test, implement the feature,
+and send me a pull request.
+
+## Tests
+Pretty standard. Just run `rake` or `rspec`.
+
+## Contributing
+
+1. Fork it ( http://github.com/pd/yard_types/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Credits
+The bulk of the parser was [written by lsegal](lsegal-parser); unfortunately, it
+was never released as a gem, and has sat untouched for 5 years. I've only modified
+the parser to better support `Hash<A, B>` syntax and to use more consistent
+naming patterns.
+
+[type-parser]: http://yardoc.org/types
+[lsegel-parser]: https://github.com/lsegal/yard-types-parser

data/Rakefile

@@ -0,0 +1,5 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec

data/lib/yard_types/parser.rb

@@ -0,0 +1,96 @@
+require "yard_types/types"
+
+module YardTypes
+
+  # Initial code taken from https://github.com/lsegal/yard-types-parser --
+  # unfortunately that was never released as a gem; and the code on master
+  # doesn't actually run.
+  #
+  # @api private
+  # @see YardTypes.parse
+  class Parser
+    TOKENS = {
+      collection_start: /</,
+      collection_end: />/,
+      tuple_start: /\(/,
+      tuple_end: /\)/,
+      type_name: /#\w+|((::)?\w+)+/,
+      type_next: /[,;]/,
+      whitespace: /\s+/,
+      hash_start: /\{/,
+      hash_next: /=>/,
+      hash_end: /\}/,
+      parse_end: nil
+    }
+
+    def self.parse(string)
+      TypeConstraint.new(new(string).parse)
+    end
+
+    def initialize(string)
+      @scanner = StringScanner.new(string)
+    end
+
+    def parse
+      types = []
+      type = nil
+      name = nil
+
+      loop do
+        found = false
+        TOKENS.each do |token_type, match|
+          if (match.nil? && @scanner.eos?) || (match && token = @scanner.scan(match))
+            found = true
+            case token_type
+            when :type_name
+              raise SyntaxError, "expecting END, got name '#{token}'" if name
+              name = token
+
+            when :type_next
+              raise SyntaxError, "expecting name, got '#{token}' at #{@scanner.pos}" if name.nil?
+              unless type
+                type = Type.for(name)
+              end
+              types << type
+              type = nil
+              name = nil
+
+            when :tuple_start, :collection_start
+              name ||=
+                token_type == :collection_start ? 'Array' : '<generic-tuple>'
+
+              type =
+                if name == 'Hash' && token_type == :collection_start
+                  contents = parse
+                  if contents.length != 2
+                    raise SyntaxError, "expected 2 types for key/value; got #{contents.length}"
+                  end
+
+                  HashType.new(name, [contents[0]], [contents[1]])
+                elsif token_type == :collection_start
+                  CollectionType.new(name, parse)
+                else
+                  TupleType.new(name, parse)
+                end
+
+            when :hash_start
+              name ||= "Hash"
+              type = HashType.new(name, parse, parse)
+
+            when :hash_next, :hash_end, :tuple_end, :collection_end, :parse_end
+              raise SyntaxError, "expecting name, got '#{token}'" if name.nil?
+              unless type
+                type = Type.for(name)
+              end
+              types << type
+              return types
+            end
+          end
+
+        end
+        raise SyntaxError, "invalid character at #{@scanner.peek(1)}" unless found
+      end
+    end
+  end
+
+end

data/lib/yard_types/types.rb

@@ -0,0 +1,293 @@
+module YardTypes
+
+  # A +TypeConstraint+ specifies the set of acceptable types
+  # which can satisfy the constraint. Parsing any YARD type
+  # description will return a +TypeConstraint+ instance.
+  #
+  # @see YardTypes.parse
+  class TypeConstraint
+    # @return [Array<Type>]
+    attr_reader :accepted_types
+
+    # @param types [Array<Type>] the list of acceptable types
+    def initialize(types)
+      @accepted_types = types
+    end
+
+    # @param i [Fixnum]
+    # @return [Type] the type at index +i+
+    # @todo deprecate this; remnant from original TDD'd API.
+    def [](i)
+      accepted_types[i]
+    end
+
+    # @return [Type] the first type
+    # @todo deprecate this; remnant from original TDD'd API.
+    def first
+      self[0]
+    end
+
+    # @param obj [Object] Any object.
+    # @return [Type, nil] The first type which matched +obj+,
+    #   or +nil+ if none.
+    def check(obj)
+      accepted_types.find { |t| t.check(obj) }
+    end
+
+    # @return [String] A YARD type string describing this set of
+    #   types.
+    def to_s
+      accepted_types.map(&:to_s).join(', ')
+    end
+  end
+
+  # The base class for all supported types.
+  class Type
+    # @return [String]
+    attr_accessor :name
+
+    # @todo This interface was just hacked into place while
+    #   enhancing the parser to return {DuckType}, {KindType}, etc.
+    # @api private
+    def self.for(name)
+      case name
+      when /^#/
+        DuckType.new(name)
+      when *LiteralType.names
+        LiteralType.new(name)
+      else
+        KindType.new(name)
+      end
+    end
+
+    # @param name [String]
+    def initialize(name)
+      @name = name
+    end
+
+    # @return [String] a YARD type string describing this type.
+    def to_s
+      name
+    end
+
+    # @param obj [Object] Any object.
+    # @return [Boolean] whether the object is of this type.
+    # @raise [NotImplementedError] must be handled by the subclasses.
+    def check(obj)
+      raise NotImplementedError
+    end
+  end
+
+  # A {DuckType} constraint is specified as +#some_message+,
+  # and indicates that the object must respond to the method
+  # +some_message+.
+  class DuckType < Type
+    # @return [String] The method the object must respond to;
+    #   this does not include the leading +#+ character.
+    attr_reader :message
+
+    # @param name [String] The YARD identifier, eg +#some_message+.
+    def initialize(name)
+      @name    = name
+      @message = name[1..-1]
+    end
+
+    # @param (see Type#check)
+    # @return [Boolean] +true+ if the object responds to +message+.
+    def check(obj)
+      obj.respond_to? message
+    end
+  end
+
+  # A {KindType} constraint is specified as +SomeModule+ or
+  # +SomeClass+, and indicates that the object must be a kind of that
+  # module.
+  class KindType < Type
+    # Type checks a given object. Special consideration is given to
+    # the pseudo-class +Boolean+, which does not actually exist in Ruby,
+    # but is commonly used to mean +TrueClass, FalseClass+.
+    #
+    # @param (see Type#check)
+    # @return [Boolean] +true+ if +obj.kind_of?(constant)+.
+    def check(obj)
+      if name == 'Boolean'
+        obj == true || obj == false
+      else
+        obj.kind_of? constant
+      end
+    end
+
+    # @return [Module] the constant specified by +name+.
+    # @raise [TypeError] if the constant is neither a module nor a class
+    # @raise [NameError] if the specified constant could not be loaded.
+    def constant
+      @constant ||=
+        begin
+          const = name.split('::').reduce(Object) { |namespace, const|
+            namespace.const_get(const)
+          }
+
+          unless const.kind_of?(Module)
+            raise TypeError, "class or module required; #{name} is a #{const.class}"
+          end
+
+          const
+        end
+    end
+  end
+
+  # A {LiteralType} constraint is specified by the name of one of YARD's
+  # supported "literals": +true+, +false+, +nil+, +void+, and +self+, and
+  # indicates that the object must be exactly one of those values.
+  #
+  # However, +void+ and +self+ have no particular meaning: +void+ is typically
+  # used solely to specify that a method returns no meaningful types; and
+  # +self+ is used to specify that a method returns its receiver, generally
+  # to indicate that calls can be chained. All values type check as valid
+  # objects for +void+ and +self+ literals.
+  class LiteralType < Type
+    # @return [Array<String>] the list of supported literal identifiers.
+    def self.names
+      @literal_names ||= %w(true false nil void self)
+    end
+
+    # @param (see Type#check)
+    # @return [Boolean] +true+ if the object is exactly +true+, +false+, or
+    #   +nil+ (depending on the value of +name+); for +void+ and +self+
+    #   types, this method *always* returns +true+.
+    # @raise [NotImplementedError] if an unsupported literal name is to be
+    #   tested against.
+    def check(obj)
+      case name
+      when 'true'         then obj == true
+      when 'false'        then obj == false
+      when 'nil'          then obj == nil
+      when 'self', 'void' then true
+      else raise NotImplementedError, "Unsupported literal type: #{name.inspect}"
+      end
+    end
+  end
+
+  # A {CollectionType} is specified with the syntax +Kind<Some, #thing>+, and
+  # indicates that the object is a kind of +Kind+, containing only objects which
+  # type check against +Some+ or +#thing+.
+  #
+  # @todo The current implementation of type checking here requires that the collection
+  #   respond to +all?+; this may not be ideal.
+  class CollectionType < Type
+    # @return [Array<Type>] the acceptable types for this collection's contents.
+    attr_accessor :types
+
+    # @param name [String] the name of the module the collection must be a kind of.
+    # @param types [Array<Type>] the acceptable types for the collection's contents.
+    def initialize(name, types)
+      @name = name
+      @types = types
+    end
+
+    # @return (see Type#to_s)
+    def to_s
+      "%s<%s>" % [name, types.map(&:to_s).join(', ')]
+    end
+
+    # @param (see Type#check)
+    # @return [Boolean] +true+ if the object is both a kind of +name+, and all of
+    #   its contents (if any) are of the types in +types+. Any combination, order,
+    #   and count of content types is acceptable.
+    def check(obj)
+      return false unless KindType.new(name).check(obj)
+
+      obj.all? do |el|
+        # TODO -- could probably just use another TypeConstraint here
+        types.any? { |type| type.check(el) }
+      end
+    end
+  end
+
+  # A {TupleType} is specified with the syntax +(Some, Types, #here)+, and indicates
+  # that the contents of the collection must be exactly that size, and each element
+  # must be of the exact type specified for that index.
+  #
+  # @todo The current implementation of type checking here requires that the collection
+  #   respond to both +length+ and +[]+; this may not be ideal.
+  class TupleType < CollectionType
+    def initialize(name, types)
+      @name  = name == '<generic-tuple>' ? nil : name
+      @types = types
+    end
+
+    # @return (see Type#to_s)
+    def to_s
+      "%s(%s)" % [name, types.map(&:to_s).join(', ')]
+    end
+
+    # @param (see Type#check)
+    # @return [Boolean] +true+ if the collection's +length+ is exactly the length of
+    #   the expected +types+, and each element with the collection is of the type
+    #   specified for that index by +types+.
+    def check(obj)
+      return false unless name.nil? || KindType.new(name).check(obj)
+      return false unless obj.respond_to?(:length) && obj.respond_to?(:[])
+      return false unless obj.length == types.length
+
+      enum = types.to_enum
+      enum.with_index.all? do |t, i|
+        t.check(obj[i])
+      end
+    end
+  end
+
+  # A {HashType} is specified with the syntax +{KeyType =>
+  # ValueType}+, and indicates that all keys in the hash must be of
+  # type +KeyType+, and all values must be of type +ValueType+.
+  #
+  # An alternate syntax for {HashType} is also available as +Hash<A,
+  # B>+, but its usage is not recommended; it is less capable than the
+  # +{A => B}+ syntax, as some inner type constraints can not be
+  # parsed reliably.
+  #
+  # A {HashType} actually only requires that the object respond to
+  # both +keys+ and +values+; it should be capable of type checking
+  # any object which conforms to that interface.
+  #
+  # @todo Enforce kind, eg +HashWithIndifferentAccess{#to_sym => Array}+,
+  #   in case you _really_ care that it's indifferent. Maybe?
+  class HashType < Type
+    # @return [Array<Type>] the set of acceptable types for keys
+    attr_reader :key_types
+
+    # @return [Array<Type>] the set of acceptable types for values
+    attr_reader :value_types
+
+    # @param name [String] the kind of the expected object; currently unused.
+    # @param key_types [Array<Type>] the set of acceptable types for keys
+    # @param value_types [Array<Type>] the set of acceptable types for values
+    def initialize(name, key_types, value_types)
+      @name = name
+      @key_types = key_types
+      @value_types = value_types
+    end
+
+    # Unlike the other types, {HashType} can result from two alternate syntaxes;
+    # however, this method will *only* return the +{A => B}+ syntax.
+    #
+    # @return (see Type#to_s)
+    def to_s
+      "{%s => %s}" % [
+        key_types.map(&:to_s).join(', '),
+        value_types.map(&:to_s).join(', ')
+      ]
+    end
+
+    # @param (see Type#check)
+    # @return [Boolean] +true+ if the object responds to both +keys+ and +values+,
+    #   and every key type checks against a type in +key_types+, and every value
+    #   type checks against a type in +value_types+.
+    def check(obj)
+      return false unless obj.respond_to?(:keys) && obj.respond_to?(:values)
+      obj.keys.all? { |key| key_types.any? { |t| t.check(key) } } &&
+        obj.values.all? { |value| value_types.any? { |t| t.check(value) } }
+    end
+  end
+
+end

data/lib/yard_types/version.rb

@@ -0,0 +1,3 @@
+module YardTypes
+  VERSION = "0.0.1"
+end

data/lib/yard_types.rb

@@ -0,0 +1,55 @@
+require "yard_types/version"
+require "yard_types/types"
+require "yard_types/parser"
+
+module YardTypes
+  extend self
+
+  class Result
+    def initialize(pass = false)
+      @pass = pass
+    end
+
+    def success?
+      @pass == true
+    end
+  end
+
+  class Success < Result
+    def initialize
+      super(true)
+    end
+  end
+
+  class Failure < Result
+    def initialize
+      super(false)
+    end
+  end
+
+  # Parse a type string using the {Parser}, and return a
+  # {TypeConstraint} instance representing the described
+  # type.
+  #
+  # @param type [String, Array<String>] The YARD type description
+  # @return [TypeConstraint]
+  # @raise [SyntaxError] if the string could not be parsed
+  # @example
+  #   type = YardTypes.parse('MyClass, #quacks_like_my_class')
+  #   type.check(some_object)
+  def parse(type)
+    type = type.join(', ') if type.respond_to?(:join)
+    Parser.parse(type)
+  end
+
+  # @return [Result]
+  # @todo deprecate; rename it +check+ to match everything else.
+  def validate(type, obj)
+    constraint = parse(type)
+    if constraint.check(obj)
+      Success.new
+    else
+      Failure.new
+    end
+  end
+end

data/spec/errors_spec.rb

@@ -0,0 +1,18 @@
+require 'spec_helper'
+
+describe 'Defensive error raising' do
+  specify 'Type#check raises NotImplementedError' do
+    type = YardTypes::Type.new('Foo')
+    expect { type.check(nil) }.to raise_error(NotImplementedError)
+  end
+
+  specify 'LiteralType raises when checking for an unsupported literal' do
+    type = YardTypes::LiteralType.new('zero')
+    expect { type.check(0) }.to raise_error(NotImplementedError, /zero/)
+  end
+
+  specify 'KindType raises when its constant is neither module nor class' do
+    type = YardTypes::KindType.new('Math::PI')
+    expect { type.check(:anything) }.to raise_error(TypeError, 'class or module required; Math::PI is a Float')
+  end
+end

data/spec/parsing_spec.rb

@@ -0,0 +1,175 @@
+require 'spec_helper'
+
+describe YardTypes, 'parsing' do
+  def parse(type_string)
+    YardTypes.parse(type_string)
+  end
+
+  matcher :be_type_class do |type|
+    def type_class(type_identifier)
+      YardTypes.const_get("#{type_identifier.to_s.capitalize}Type")
+    end
+
+    match do |type_string|
+      result = YardTypes.parse(type_string)
+      result.first.instance_of? type_class(type)
+    end
+
+    description do |type_string|
+      "'#{type_string}' parses into a #{type_class(type).name} instance"
+    end
+
+    failure_message do |type_string|
+      "expected '#{type_string}' to parse into a #{type_class(type).name} instance"
+    end
+
+    failure_message_when_negated do |type_string|
+      "expected '#{type_string}' not to parse into a #{type_class(type).name} instance, but did"
+    end
+  end
+
+  matcher :have_inner_types do |*expected_inner_types|
+    def collection?(type)
+      type.respond_to?(:types)
+    end
+
+    def matching_count?(actual, expected)
+      actual.size == expected.size
+    end
+
+    def matching_type_classes?(actual, expected)
+      actual.zip(expected).all? do |type, (klass_name, type_name)|
+        klass = YardTypes.const_get("#{klass_name.to_s.capitalize}Type")
+        type.is_a?(klass) && type.name == type_name
+      end
+    end
+
+    match do |type_string|
+      type = YardTypes.parse(type_string).first
+      collection?(type) &&
+        matching_count?(type.types, expected_inner_types) &&
+        matching_type_classes?(type.types, expected_inner_types)
+    end
+  end
+
+  specify 'literals' do
+    expect('true').to  be_type_class(:literal)
+    expect('false').to be_type_class(:literal)
+    expect('nil').to   be_type_class(:literal)
+    expect('void').to  be_type_class(:literal)
+    expect('self').to  be_type_class(:literal)
+  end
+
+  specify 'duck' do
+    expect('#foo').to be_type_class(:duck)
+  end
+
+  specify 'kind' do
+    expect('Foo').to   be_type_class(:kind)
+    expect('Array').to be_type_class(:kind)
+    expect('Hash').to  be_type_class(:kind)
+  end
+
+  context 'parameterized array' do
+    specify 'not bare `Array` type' do
+      expect('Array').not_to be_type_class(:collection)
+    end
+
+    specify 'Array<...>' do
+      expect('Array<String>').to be_type_class(:collection)
+      expect('Array<#foo>').to   be_type_class(:collection)
+      expect('Array<#a, #b>').to be_type_class(:collection)
+    end
+
+    specify 'inner types' do
+      expect('Array<String>').to have_inner_types([:kind, 'String'])
+
+      expect('Array<String, #to_date>').to have_inner_types([:kind, 'String'],
+                                                            [:duck, '#to_date'])
+    end
+  end
+
+  context 'tuples' do
+    specify '(...)' do
+      expect('(String)').to be_type_class(:tuple)
+      expect('(String, #to_date, true)').to be_type_class(:tuple)
+    end
+
+    specify 'inner types' do
+      expect('(String)').to have_inner_types([:kind, 'String'])
+
+      expect('(String, #to_date, true)').to have_inner_types([:kind, 'String'],
+                                                             [:duck, '#to_date'],
+                                                             [:literal, 'true'])
+    end
+  end
+
+  context 'hashes' do
+    specify 'Hash<a, b>' do
+      expect('Hash<#a, #b>').to be_type_class(:hash)
+      expect('Hash<Fixnum, String>').to be_type_class(:hash)
+      expect('Hash<(#some, #tuple), Array<#to_date>>').to be_type_class(:hash)
+    end
+
+    specify 'Hash<a> | Hash<a, b, c> => SyntaxError' do
+      expect { parse('Hash<a>') }.to raise_error(SyntaxError)
+      expect { parse('Hash<a, b, c>') }.to raise_error(SyntaxError)
+    end
+
+    specify '{a => b}' do
+      expect('{A => B}').to be_type_class(:hash)
+      expect('{#a, #b => #to_date}').to be_type_class(:hash)
+    end
+  end
+end
+
+describe YardTypes::Type, '.parse' do
+  it "can accept a single YARD type string" do
+    constraint = YardTypes.parse('Array, Hash')
+    expect(constraint).to be_instance_of(YardTypes::TypeConstraint)
+    expect(constraint.to_s).to eq('Array, Hash')
+  end
+
+  it "can accept an array of individual type strings, and return a single Constraint" do
+    constraint = YardTypes.parse(['Array', 'Hash'])
+    expect(constraint).to be_instance_of(YardTypes::TypeConstraint)
+    expect(constraint.to_s).to eq('Array, Hash')
+  end
+end
+
+describe YardTypes::Type, '#to_s' do
+  [
+    # Kind
+    'String', 'Boolean', 'Array', 'String, Symbol',
+
+    # Duck
+    '#foo', '#foo, #bar',
+
+    # Literals
+    'true', 'false', 'self', 'nil', 'void', 'true, false, nil',
+
+    # Collection
+    'Array<Fixnum>', 'Array<Fixnum, (#to_i, #to_f)>', 'Set<Date>',
+
+    # Tuple
+    '(String, Boolean)', '(A, B), (C, D)',
+
+    # Hash
+    '{String => Symbol}', '{#a, #b => (A, B)}', '{#foo => #bar}, {Fixnum => String}',
+
+    # Crazy
+    '(Array<(#foo, #bar), {String => Symbol}>, #to_sym, (nil, Boolean))'
+  ].each do |string|
+
+    specify string do
+      parsed = YardTypes.parse(string)
+      expect(parsed.to_s).to eq(string)
+    end
+
+  end
+
+  it "does not preserve Hash<> notation" do
+    parsed = YardTypes.parse('Hash<(#a, #b), Symbol>')
+    expect(parsed.to_s).to eq('{(#a, #b) => Symbol}')
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,13 @@
+require 'simplecov'
+SimpleCov.start do
+  add_filter "/spec/"
+end
+
+require 'yard_types'
+require 'pry'
+
+RSpec.configure do |config|
+  config.order = :rand
+  config.filter_run focus: true
+  config.run_all_when_everything_filtered = true
+end

data/spec/type_checking_spec.rb

@@ -0,0 +1,245 @@
+require 'spec_helper'
+require 'set'
+
+describe YardTypes, 'type checking' do
+  matcher :type_check do |obj|
+    match do |type|
+      result = YardTypes.validate(type, obj)
+      result.success?
+    end
+
+    description do |type|
+      "type checks against #{type.inspect}"
+    end
+
+    failure_message do |type|
+      "expected `#{obj.inspect}` to type check against #{type.inspect}"
+    end
+
+    failure_message_when_negated do |type|
+      "expected `#{obj.inspect}` not to type check against #{type.inspect}"
+    end
+  end
+
+  context 'ducks' do
+    specify 'responds' do
+      expect('#to_s').to    type_check(nil)
+      expect('#reverse').to type_check('foo')
+      expect('#name').to    type_check(Class)
+    end
+
+    specify 'does not respond' do
+      expect('#bogus').not_to type_check(nil)
+    end
+  end
+
+  context 'kinds' do
+    specify 'is kind_of' do
+      expect('String').to type_check('')
+      expect('Object').to type_check([])
+    end
+
+    specify 'is not kind_of' do
+      expect('String').not_to type_check([])
+    end
+
+    specify 'Boolean == true || false' do
+      expect('Boolean').to     type_check(true)
+      expect('Boolean').to     type_check(false)
+      expect('Boolean').not_to type_check(nil)
+    end
+
+    specify 'constant resolution' do
+      expect('YardTypes::DuckType').to type_check(YardTypes::DuckType.new('#foo'))
+    end
+
+    specify 'unknown constant' do
+      expect {
+        type = YardTypes.parse('ReversedString')[0] # mind the typo
+        type.check('gnirts')
+      }.to raise_error(NameError)
+    end
+  end
+
+  context 'arrays' do
+    specify 'inner type' do
+      # Empty always passes
+      expect('Array<String>').to type_check([])
+
+      # Every element passes
+      expect('Array<#reverse>').to type_check(['foo', 'bar'])
+      expect('Array<#reverse>').to type_check([['a'], 'foo'])
+
+      # Every element fails
+      expect('Array<#reverse>').not_to type_check([1])
+
+      # Some element fails
+      expect('Array<#reverse>').not_to type_check(['foo', 1])
+    end
+  end
+
+  context 'alternate collection types' do
+    specify 'Set<Symbol>' do
+      array = [:foo, :bar]
+      set   = Set.new(array)
+
+      expect('Set<Symbol>').to     type_check(set)
+      expect('Set<Symbol>').not_to type_check(array)
+    end
+  end
+
+  context 'tuples' do
+    class ::MyTuple < Array
+    end
+
+    let(:type) { '(String, Fixnum, #reverse)' }
+
+    specify 'matches' do
+      expect(type).to type_check(['foo', 1,   []])
+    end
+
+    specify 'one type is wrong' do
+      expect(type).not_to type_check([:nope, 1,   []])
+      expect(type).not_to type_check(['foo', 1.0, []])
+      expect(type).not_to type_check(['foo', 1,   nil])
+    end
+
+    specify 'invalid length' do
+      expect(type).not_to type_check([])
+      expect(type).not_to type_check(['foo'])
+      expect(type).not_to type_check(['foo', 1])
+      expect(type).not_to type_check(['foo', 1, [], true])
+    end
+
+    specify 'unspecified kind accepts any kind' do
+      tuple = MyTuple.new
+      tuple[0] = 'hi'
+      tuple[1] = 1
+      tuple[2] = []
+
+      expect(type).to type_check(tuple)
+    end
+
+    context 'specified kind' do
+      let(:type) { 'MyTuple(String, Fixnum)' }
+
+      specify 'kind + contents match' do
+        tuple = MyTuple.new
+        tuple[0] = 'hi'
+        tuple[1] = 1
+
+        expect(type).to type_check(tuple)
+      end
+
+      specify 'kind matches, contents do not' do
+        expect(type).not_to type_check(MyTuple.new)
+      end
+
+      specify 'contents match, but kind does not' do
+        expect(type).not_to type_check(['hi', 1])
+      end
+    end
+  end
+
+  context 'hash' do
+    context 'Hash<> syntax' do
+      let(:type) { 'Hash<Fixnum, String>' }
+
+      specify 'matches' do
+        expect(type).to type_check({ 1 => 'foo', 2 => 'bar' })
+      end
+
+      specify 'wrong key type' do
+        expect(type).not_to type_check({ 1.0 => 'foo' })
+        expect(type).not_to type_check({ 1 => 'foo', :wrong => 'bar' })
+      end
+
+      specify 'wrong value type' do
+        expect(type).not_to type_check({ 1 => :foo })
+        expect(type).not_to type_check({ 1 => 'foo', 2 => :bar })
+      end
+
+      specify 'quacks like a hash' do
+        map_type = Struct.new(:keys, :values)
+        hash_map = map_type.new([1, 2], ['three', 'four'])
+        expect(type).to type_check(hash_map)
+      end
+    end
+
+    context 'Hash{} syntax' do
+      let(:type) { '{Boolean => #reverse}' }
+
+      specify 'matches' do
+        expect(type).to type_check(false => [])
+        expect(type).to type_check(true  => 'foo', false => [])
+      end
+
+      specify 'wrong key type' do
+        expect(type).not_to type_check(:false => [])
+        expect(type).not_to type_check(false => [], 'true' => 'bar')
+      end
+
+      specify 'wrong value type' do
+        expect(type).not_to type_check(true => :fail)
+        expect(type).not_to type_check(true => 'pass', false => :fail)
+      end
+
+      specify 'quacks like a hash' do
+        map_type = Struct.new(:keys, :values)
+        hash_map = map_type.new([true, false], ['three', [:four]])
+        expect(type).to type_check(hash_map)
+      end
+    end
+  end
+
+  context 'literals' do
+    specify 'nil' do
+      expect('nil').to     type_check(nil)
+      expect('nil').not_to type_check(false)
+    end
+
+    specify 'true' do
+      expect('true').to     type_check(true)
+      expect('true').not_to type_check(false)
+      expect('true').not_to type_check(nil)
+    end
+
+    specify 'false' do
+      expect('false').to     type_check(false)
+      expect('false').not_to type_check(true)
+      expect('false').not_to type_check(nil)
+    end
+
+    specify 'void' do
+      expect('void').to type_check(nil)
+      expect('void').to type_check('')
+      expect('void').to type_check(['anything', :really])
+    end
+
+    specify 'self' do
+      expect('self').to type_check(nil)
+      expect('self').to type_check('')
+      expect('self').to type_check(['anything', :really])
+    end
+  end
+
+  context 'multiple acceptable types' do
+    specify 'String, Symbol' do
+      expect('String, Symbol').to     type_check('foo')
+      expect('String, Symbol').to     type_check(:foo)
+      expect('String, Symbol').not_to type_check([])
+      expect('String, Symbol').not_to type_check(['foo', :foo])
+    end
+
+    specify 'Array<A, B>' do
+      expect('Array<Fixnum, #to_i>').to type_check([])
+      expect('Array<Fixnum, #to_i>').to type_check([1])
+      expect('Array<Fixnum, #to_i>').to type_check(['1'])
+      expect('Array<Fixnum, #to_i>').to type_check([nil])
+
+      expect('Array<Fixnum, #to_i>').not_to type_check([:oops])
+      expect('Array<Fixnum, #to_i>').not_to type_check(nil)
+    end
+  end
+
+end

data/yard_type.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'yard_types/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "yard_types"
+  spec.version       = YardTypes::VERSION
+  spec.authors       = ["Kyle Hargraves"]
+  spec.email         = ["pd@krh.me"]
+  spec.summary       = %q{Parse and validate objects against YARD type descriptions.}
+  spec.description   = %q{Your API docs say you return Array<#to_date>, but do you really?}
+  spec.homepage      = "https://github.com/pd/yard_types"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "simplecov", "~> 0.7.1"
+  spec.add_development_dependency "pry", "> 0"
+end

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: yard_types
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Kyle Hargraves
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-07-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Your API docs say you return Array<#to_date>, but do you really?
+email:
+- pd@krh.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/yard_types.rb
+- lib/yard_types/parser.rb
+- lib/yard_types/types.rb
+- lib/yard_types/version.rb
+- spec/errors_spec.rb
+- spec/parsing_spec.rb
+- spec/spec_helper.rb
+- spec/type_checking_spec.rb
+- yard_type.gemspec
+homepage: https://github.com/pd/yard_types
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.0
+signing_key: 
+specification_version: 4
+summary: Parse and validate objects against YARD type descriptions.
+test_files:
+- spec/errors_spec.rb
+- spec/parsing_spec.rb
+- spec/spec_helper.rb
+- spec/type_checking_spec.rb