yard_types 0.0.1 → 0.1.1

data/.travis.yml

@@ -1,4 +1,6 @@
 language: ruby
+install:
+  - bundle install --retry=3
 rvm:
   - 1.9.3
   - 2.0.0

data/Gemfile

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

data/README.md

@@ -1,6 +1,11 @@
 # yard_types
 
+[![Gem Version](https://badge.fury.io/rb/yard_types.svg)](http://badge.fury.io/rb/yard_types)
 [![Build Status](https://travis-ci.org/pd/yard_types.svg?branch=master)](https://travis-ci.org/pd/yard_types)
+[![Dependency Status](https://gemnasium.com/pd/yard_types.svg)](https://gemnasium.com/pd/yard_types)
+[![Code Climate](https://codeclimate.com/github/pd/yard_types.png)](https://codeclimate.com/github/pd/yard_types)
+[![Coverage Status](https://coveralls.io/repos/pd/yard_types/badge.png)](https://coveralls.io/r/pd/yard_types)
+[![Inline docs](http://inch-ci.org/github/pd/yard_types.svg?branch=master)](http://inch-ci.org/github/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.

data/lib/yard_types/types.rb

@@ -1,12 +1,25 @@
 module YardTypes
 
+  # @api private
+  module OrList #:nodoc:
+    def or_list(ary)
+      size = ary.size
+      ary.to_enum.with_index.inject('') do |acc, (s, index)|
+        acc << s.to_s
+        acc << ", "    if index < size - 2
+        acc << ", or " if index == size - 2
+        acc
+      end
+    end
+  end
+
   # 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>]
+    # @return [Array<Type>] the list of types that will satisfy this constraint
     attr_reader :accepted_types
 
     # @param types [Array<Type>] the list of acceptable types
@@ -41,9 +54,9 @@ module YardTypes
     end
   end
 
-  # The base class for all supported types.
+  # @abstract The base class for all supported types.
   class Type
-    # @return [String]
+    # @return [String] the YARD string naming this type
     attr_accessor :name
 
     # @todo This interface was just hacked into place while
@@ -70,6 +83,11 @@ module YardTypes
       name
     end
 
+    # @return [String] an English phrase describing this type.
+    def description
+      raise NotImplementedError
+    end
+
     # @param obj [Object] Any object.
     # @return [Boolean] whether the object is of this type.
     # @raise [NotImplementedError] must be handled by the subclasses.
@@ -92,6 +110,11 @@ module YardTypes
       @message = name[1..-1]
     end
 
+    # (see Type#description)
+    def description
+      "an object that responds to #{name}"
+    end
+
     # @param (see Type#check)
     # @return [Boolean] +true+ if the object responds to +message+.
     def check(obj)
@@ -117,14 +140,19 @@ module YardTypes
       end
     end
 
+    # (see Type#description)
+    def description
+      name
+    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)
+          const = name.split('::').reduce(Object) { |namespace, inner_const|
+            namespace.const_get(inner_const)
           }
 
           unless const.kind_of?(Module)
@@ -151,6 +179,11 @@ module YardTypes
       @literal_names ||= %w(true false nil void self)
     end
 
+    # (see Type#description)
+    def description
+      name
+    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+
@@ -175,6 +208,8 @@ module YardTypes
   # @todo The current implementation of type checking here requires that the collection
   #   respond to +all?+; this may not be ideal.
   class CollectionType < Type
+    include OrList
+
     # @return [Array<Type>] the acceptable types for this collection's contents.
     attr_accessor :types
 
@@ -185,11 +220,18 @@ module YardTypes
       @types = types
     end
 
-    # @return (see Type#to_s)
+    # (see Type#to_s)
     def to_s
       "%s<%s>" % [name, types.map(&:to_s).join(', ')]
     end
 
+    # (see Type#description)
+    def description
+      article = name[0] =~ /[aeiou]/i ? 'an' : 'a'
+      type_descriptions = types.map(&:description)
+      "#{article} #{name} of (#{or_list(type_descriptions)})"
+    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,
@@ -216,11 +258,19 @@ module YardTypes
       @types = types
     end
 
-    # @return (see Type#to_s)
+    # (see Type#to_s)
     def to_s
       "%s(%s)" % [name, types.map(&:to_s).join(', ')]
     end
 
+    # (see Type#description)
+    def description
+      kind = name || 'tuple'
+      article = kind[0] =~ /[aeiou]/i ? 'an' : 'a'
+      contents = types.map(&:description).join(', ')
+      "#{article} #{kind} containing (#{contents})"
+    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
@@ -253,6 +303,8 @@ module YardTypes
   # @todo Enforce kind, eg +HashWithIndifferentAccess{#to_sym => Array}+,
   #   in case you _really_ care that it's indifferent. Maybe?
   class HashType < Type
+    include OrList
+
     # @return [Array<Type>] the set of acceptable types for keys
     attr_reader :key_types
 
@@ -279,6 +331,14 @@ module YardTypes
       ]
     end
 
+    # (see Type#description)
+    def description
+      article = name[0] =~ /[aeiou]/i ? 'an' : 'a'
+      key_descriptions = or_list(key_types.map(&:description))
+      value_descriptions = or_list(value_types.map(&:description))
+      "#{article} #{name} with keys of (#{key_descriptions}) and values of (#{value_descriptions})"
+    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
@@ -289,5 +349,4 @@ module YardTypes
         obj.values.all? { |value| value_types.any? { |t| t.check(value) } }
     end
   end
-
 end

data/lib/yard_types/version.rb

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

data/lib/yard_types.rb

@@ -2,9 +2,12 @@ require "yard_types/version"
 require "yard_types/types"
 require "yard_types/parser"
 
+# {YardTypes} provides a parser for YARD type descriptions, and
+# testing whether objects are of the specified types.
 module YardTypes
   extend self
 
+  # @abstract Base class for {Success} and {Failure}
   class Result
     def initialize(pass = false)
       @pass = pass
@@ -15,12 +18,18 @@ module YardTypes
     end
   end
 
+  # Returned from {YardTypes.validate} when a type check succeeds,
+  # providing the particular type which satisfied the
+  # {TypeConstraint}.
   class Success < Result
     def initialize
       super(true)
     end
   end
 
+  # Returned from {YardTypes.validate} when a type check fails,
+  # providing a reference to the {TypeConstraint} and a means of
+  # generating error messages describing the error.
   class Failure < Result
     def initialize
       super(false)
@@ -42,7 +51,12 @@ module YardTypes
     Parser.parse(type)
   end
 
-  # @return [Result]
+  # Parses a type identifier with {#parse}, then validates that the
+  # given +obj+ satisfies the type constraint.
+  #
+  # @param type [String, Array<String>] A YARD type description; see {#parse}.
+  # @param obj [Object] Any object.
+  # @return [Result] success or failure.
   # @todo deprecate; rename it +check+ to match everything else.
   def validate(type, obj)
     constraint = parse(type)

data/spec/errors_spec.rb

@@ -6,6 +6,11 @@ describe 'Defensive error raising' do
     expect { type.check(nil) }.to raise_error(NotImplementedError)
   end
 
+  specify 'Type#description raises NotImplementedError' do
+    type = YardTypes::Type.new('Foo')
+    expect { type.description }.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/)

data/spec/spec_helper.rb

@@ -1,4 +1,11 @@
 require 'simplecov'
+require 'coveralls'
+
+SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter[
+  Coveralls::SimpleCov::Formatter,
+  SimpleCov::Formatter::HTMLFormatter,
+]
+
 SimpleCov.start do
   add_filter "/spec/"
 end

data/spec/types_spec.rb

@@ -0,0 +1,83 @@
+require 'spec_helper'
+
+module YardTypes
+  describe DuckType do
+    context '#description' do
+      it "says the object should respond to its message" do
+        type = DuckType.new('#msg')
+        expect(type.description).to eq('an object that responds to #msg')
+      end
+    end
+  end
+
+  describe KindType do
+    context '#description' do
+      it "says the object should be a kind of its module" do
+        type = KindType.new('Struct')
+        expect(type.description).to eq('Struct')
+      end
+    end
+  end
+
+  describe LiteralType do
+    context '#description' do
+      LiteralType.names.each do |literal|
+        specify literal do
+          type = LiteralType.new(literal)
+          expect(type.description).to eq(literal)
+        end
+      end
+    end
+  end
+
+  describe CollectionType do
+    context '#description' do
+      let(:type) { CollectionType.new('Array', [KindType.new('Foo'), DuckType.new('#bar')]) }
+
+      it "specifies its Kind" do
+        expect(type.description).to match(/Array/)
+      end
+
+      it "specifies its inner content types" do
+        expect(type.description).to match(/Foo, or an object that responds to #bar/)
+      end
+    end
+  end
+
+  describe TupleType do
+    context '#description' do
+      let(:type) { TupleType.new('Array', [LiteralType.new('false'), KindType.new('Set')]) }
+
+      it 'specifies its Kind' do
+        expect(type.description).to match(/Array/)
+      end
+
+      it 'specifies its contents, in order' do
+        expect(type.description).to match(/\(false, Set\)/)
+      end
+
+      it 'omits its Kind if unspecified' do
+        type = YardTypes.parse('(Set, Numeric)').accepted_types.first
+        expect(type.description).to eql('a tuple containing (Set, Numeric)')
+      end
+    end
+  end
+
+  describe HashType do
+    context '#description' do
+      let(:type) { HashType.new('Hash', [DuckType.new('#to_s')], [KindType.new('Date'), KindType.new('DateTime')]) }
+
+      it "specifies its Kind" do
+        expect(type.description).to match(/Hash/)
+      end
+
+      it "specifies its key types" do
+        expect(type.description).to match(/keys of \(an object that responds to #to_s\)/)
+      end
+
+      it "specifies its value types" do
+        expect(type.description).to match(/values of \(Date, or DateTime\)/)
+      end
+    end
+  end
+end

data/yard_type.gemspec

@@ -23,4 +23,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "simplecov", "~> 0.7.1"
   spec.add_development_dependency "pry", "> 0"
+  spec.add_development_dependency "coveralls", "> 0"
 end

metadata

@@ -1,83 +1,110 @@
 --- !ruby/object:Gem::Specification
 name: yard_types
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.1
+  prerelease: 
 platform: ruby
 authors:
 - Kyle Hargraves
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-16 00:00:00.000000000 Z
+date: 2014-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.5'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.5'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: 0.7.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: 0.7.1
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - ">"
+    - - ! '>'
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - ">"
+    - - ! '>'
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>'
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>'
       - !ruby/object:Gem::Version
         version: '0'
 description: Your API docs say you return Array<#to_date>, but do you really?
@@ -87,8 +114,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- ".travis.yml"
+- .gitignore
+- .travis.yml
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -101,33 +128,42 @@ files:
 - spec/parsing_spec.rb
 - spec/spec_helper.rb
 - spec/type_checking_spec.rb
+- spec/types_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
+  none: false
   requirements:
-  - - ">="
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 1195132354547834267
 required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - ">="
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 1195132354547834267
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.0
+rubygems_version: 1.8.23.2
 signing_key: 
-specification_version: 4
+specification_version: 3
 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
+- spec/types_spec.rb

checksums.yaml

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