taipo 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cb7fcacea028acafa7344ccfc04fbc3c66e50c13
-  data.tar.gz: 052b196e3ed53b4ade6d95abee2b57a266c12a9f
+  metadata.gz: f2d4388512ddb3fd352644adc19c2d597617c1ba
+  data.tar.gz: 424f50365c4c88bf5d3d511cf66bfdf59431504c
 SHA512:
-  metadata.gz: 6cced24c850830e10102f010b0b098ff5ed7ebab426f10cee4b51dcdf1ff29622721e75228b9fc4be9f6fa35b8e4917e14961254a4dbfddb0b8110969aad3b0a
-  data.tar.gz: 4e9bd2e042ef2f87808bbdab7c10657d96f75bb969aa725e0b02666e4160a433eb3279b601c232c87f4fce37163b23204d504a31a8307ee0649b7846ff510de4
+  metadata.gz: 13da1bffba5a77cc4a1c2040c0fe9d6ef0112c69968c30b89ca72bcff068f303593dbdc6ed276056571ae037a3170c41458e77911f3e0227527ddd9d8cef6efc
+  data.tar.gz: 167bffef5e9d7f24f0af153b3dfbb44d655067f0b1223a1505447e52e9cce84ef00895d60b4eddacdaedf85669296d7c504396a47e274f977288b146a343a9c0

data/.travis.yml

@@ -3,7 +3,7 @@ env:
    - CC_TEST_REPORTER_ID=787a2f89b15c637323c7340d65ec17e898ac44480706b4b4122ea040c2a88f1d
 language: ruby
 rvm:
- - 2.4.1
+ - 2.4.2
 before_script:
  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
  - chmod +x ./cc-test-reporter

data/README.md

@@ -22,7 +22,10 @@ Run `gem install taipo` or add `gem 'taipo'` to your `Gemfile`.
 
 ## Usage
 
-Taipo provides two methods in the `Taipo::Check` module that we can mix into our classes: `#check` and `#review`.
+Taipo can be used to check variables within a given context or check the return value of a given method:
+
+* the `Taipo::Check` module provides two methods: `#check` and `#review`:
+* the `Taipo::Result` module provides one method: `.result`.
 
 ### #check
 
@@ -78,6 +81,32 @@ The method `#review` will put the invalid arguments into an array and return tha
 
 [rdr]: http://www.rubydoc.info/gems/taipo/Taipo/Check#review-instance_method
 
+### .result
+
+```ruby
+require 'taipo'
+
+class Foo
+  include Taipo::Result
+
+  result :add, 'Integer'
+
+  def add(x, y)
+    x + y
+  end
+end
+
+foo = Foo.new
+foo.add 4, 5               #=> 9
+foo.add 'hello', 'world'   #=> Taipo::TypeError
+```
+
+The method `.result` will raise an exception if the return value of the specified method doesn't match the specified type definition.
+
+[More information about `.result`][rde] is available in the documentation.
+
+[rde]: http://www.rubydoc.info/gems/taipo/Taipo/Result/ClassMethods#result-instance_method
+
 ## Syntax
 
 Type definitions are written as Strings. Type definitions can consist of (1) names, (2) collections, (3) constraints and (4) sums.

data/lib/taipo.rb

@@ -1,33 +1,26 @@
 require 'taipo/version'
 require 'taipo/check'
-require 'taipo/parser'
+require 'taipo/result'
 
 # A library for checking the types of objects
 #
-# Taipo is primarily intended as a replacement for cumbersome, error-prone
-# guard statements a user can put in their code to ensure that the variables
-# they are handling conform to expectations.
+# Taipo is primarily intended as a replacement for verbose, error-prone guard
+# statements. With Taipo, a user can ensure that the objects they are working
+# with conform to expectations.
 #
-# By including the module {Taipo::Check}, a user can call the
-# {Taipo::Check#check} or {Taipo::Check#review} methods in their classes
-# whenever a guard statement is necessary. Expectations are written as type
-# definitions. A type definition contains the name of the type and the type
-# definitions of any elements it contains (if it is enumerable). Optional
-# constraints may be specified and sum types are also possible. See
-# {Taipo::Parser::Validater} for the full syntax.
+# Taipo consists of two user-facing parts: {Taipo::Check} and {Taipo::Result}.
+#
+# * By including the module {Taipo::Check}, a user can call
+#   {Taipo::Check#check} or {Taipo::Check#review} in their methods to
+#   check the types of one or more given variables.
 #
-# Taipo works by:
-# 1. extracting the values of the arguments to be checked from a Binding;
-# 2. transforming the type definitions provided as Strings into an array of
-#    {Taipo::TypeElement} instances; and
-# 3. checking whether the argument's value matches any of the instances of
-#    {Taipo::TypeElement} in the array.
+# * By including the module {Taipo::Result}, a user can call
+#   {Taipo::Result::ClassMethods#result} in their class definitions to check the
+#   return values of a given method.
 #
-# As syntactic sugar, the {Taipo::Check} module will by default alias
-# +Kernel#binding+ with the keyword +types+. This allows the user to call
-# {Taipo::Check#check} by writing +check types+ (with a similar syntax for
-# {Taipo::Check#review}). If the user does not want to alias, they can set
-# {Taipo.alias=} to +false+ before including or extending {Taipo::Check}.
+# Taipo provides a rich syntax to express type definitions. This includes
+# classes, collections, optionals and duck types. See
+# {Taipo::Parser::Validater} for the full syntax.
 #
 # @since 1.0.0
 # @see https://github.com/pyrmont/taipo

data/lib/taipo/cache.rb

@@ -1,6 +1,6 @@
 module Taipo
 
-  # A cache of Taipo::TypeElement created from parsed type definitions
+  # A cache of {Taipo::TypeElement} objects created from parsed type definitions
   #
   # @since 1.0.0
   # @api private
@@ -12,7 +12,8 @@ module Taipo
     # @api private
     @@Cache = {}
 
-    # Retrieve the Taipo::TypeElement object described by the type definition from the cache
+    # Retrieve the {Taipo::TypeElement} object described by the type definition
+    # from the cache
     #
     # @param k [String] the type definition
     #
@@ -25,7 +26,8 @@ module Taipo
       @@Cache[k]
     end
 
-    # Save the Taipo::TypeElement object described by the type definition in the cache
+    # Save the {Taipo::TypeElement} object described by the type definition in
+    # the cache
     #
     # @param k [String] the type definition
     # @param v [Taipo::TypeElement] the object to be saved

data/lib/taipo/check.rb

@@ -1,13 +1,21 @@
-require 'taipo/cache'
-require 'taipo/exceptions'
-require 'taipo/parser'
-require 'taipo/type_elements'
-require 'taipo/type_element'
 require 'taipo/utilities'
 
 module Taipo
 
-  # A dedicated namespace for methods meant to be included by the user
+  # A simple DSL for declaring type checks to run against specified variables
+  #
+  # {Taipo::Check} works by:
+  # 1. extracting the values of the arguments to be checked from a Binding;
+  # 2. transforming the type definitions provided as Strings into an array of
+  #    {Taipo::TypeElement} instances; and
+  # 3. checking whether the argument's value matches any of the instances of
+  #    {Taipo::TypeElement} in the array.
+  #
+  # As syntactic sugar, the {Taipo::Check} module will by default alias
+  # +Kernel#binding+ with the keyword +types+. This allows the user to call
+  # {Taipo::Check#check} by writing +check types+ (with a similar syntax for
+  # {Taipo::Check#review}). If the user does not want to alias, they can set
+  # {Taipo.alias=} to +false+ before including or extending {Taipo::Check}.
   #
   # @since 1.0.0
   module Check
@@ -70,35 +78,14 @@ module Taipo
       raise ::TypeError, msg unless context.is_a? Binding
 
       checks.reduce(Array.new) do |memo,(k,v)|
-        arg = if k[0] == '@' && self.instance_variable_defined?(k)
-                self.instance_variable_get k
-              elsif k[0] != '@' && context.local_variable_defined?(k)
-                context.local_variable_get k
-              else
-                msg = "Argument '#{k}' is not defined."
-                raise Taipo::NameError, msg
-              end
-
-        types = if hit = Taipo::Cache[v]
-                  hit
-                else
-                  Taipo::Cache[v] = Taipo::Parser.parse v
-                end
+        arg = Taipo::Utilities.extract_variable(name: k,
+                                                object: self,
+                                                context: context)
 
-        is_match = types.any? { |t| t.match? arg }
+        is_match = Taipo::Utilities.match? object: arg, definition: v
 
         unless collect_invalids || is_match
-          if Taipo::Utilities.instance_method? v
-            msg = "Object '#{k}' does not respond to #{v}."
-          elsif Taipo::Utilities.symbol? v
-            msg = "Object '#{k}' is not equal to #{v}."
-          elsif arg.is_a? Enumerable
-            type_def = Taipo::Utilities.object_to_type_def arg
-            msg = "Object '#{k}' is #{type_def} but expected #{v}."
-          else
-            msg = "Object '#{k}' is #{arg.class.name} but expected #{v}."
-          end
-          raise Taipo::TypeError, msg
+          Taipo::Utilities.throw_error object: arg, name: k, definition: v
         end
 
         (is_match) ? memo : memo.push(k)

data/lib/taipo/parser.rb

@@ -1,12 +1,7 @@
-require 'taipo/exceptions'
+require 'taipo/cache'
 require 'taipo/parser/stack'
 require 'taipo/parser/validater'
 require 'taipo/refinements'
-require 'taipo/type_elements'
-require 'taipo/type_element'
-require 'taipo/type_element/children'
-require 'taipo/type_element/constraints'
-require 'taipo/type_element/constraint'
 
 module Taipo
 
@@ -19,57 +14,24 @@ module Taipo
 
     # Return a Taipo::TypeElements object based on +str+
     #
+    # This method acts as a wrapping method to {Taipo::Parser.parse_definition}.
+    # It first checks if the type definition has already been parsed and is in
+    # Taipo's cache.
+    #
     # @param str [String] a type definition
     #
-    # @return [Taipo:TypeElements] the result
+    # @return [Taipo::TypeElements] the result
     #
     # @raise [::TypeError] if +str+ is not a String
     # @raise [Taipo::SyntaxError] if +str+ is not a valid type definition
     #
     # @since 1.0.0
     def self.parse(str)
-      Taipo::Parser::Validater.validate str
-
-      stack = Taipo::Parser::Stack.new
-      i = 0
-      subject = :implied
-      chars = str.chars
-      content = ''
-
-      while (i < chars.size)
-        reset = true
-
-        case chars[i]
-        when ' '
-          i += 1
-          next
-        when '|'
-          stack = process_sum stack, name: content
-          subject = :implied
-        when '<'
-          stack = process_collection :open, stack, name: content
-          subject = :implied
-        when '>'
-          stack = process_collection :close, stack, name: content
-          subject = :made
-        when ','
-          stack = process_component stack, name: content
-          subject = :implied
-        when '('
-          stack = process_subject stack, name: content, subject: subject
-          stack, i = process_constraints stack, chars: chars, index: i+1
-        else
-          reset = false
-          subject = :unmade
-        end
-
-        content = (reset) ? '' : content + chars[i]
-        i += 1
+      if hit = Taipo::Cache[str]
+        hit
+      else
+        Taipo::Cache[str] = Taipo::Parser.parse_definition str
       end
-
-      stack = process_end stack, name: content
-
-      stack.result
     end
 
     # Check whether the character should be skipped
@@ -128,7 +90,7 @@ module Taipo
       content = ''
       str.each_char do |c|
         if c == '#' && in_name.nil?
-          name = Taipo::TypeElement::Constraint::METHOD
+          name = '#'
           in_name = false
         elsif c == ':' && in_name.nil?
           name = 'val'
@@ -147,6 +109,60 @@ module Taipo
       return name, value
     end
 
+    # Return a Taipo::TypeElements object based on +str+
+    #
+    # @param str (see {Taipo::Parser.parse})
+    #
+    # @return (see {Taipo::Parser.parse})
+    #
+    # @raise (see {Taipo::Parser.parse})
+    #
+    # @since 1.5.0
+    # @api private
+    def self.parse_definition(str)
+      Taipo::Parser::Validater.validate str
+
+      stack = Taipo::Parser::Stack.new
+      i = 0
+      subject = :implied
+      chars = str.chars
+      content = ''
+
+      while (i < chars.size)
+        reset = true
+
+        case chars[i]
+        when ' '
+          i += 1
+          next
+        when '|'
+          stack = process_sum stack, name: content
+          subject = :implied
+        when '<'
+          stack = process_collection :open, stack, name: content
+          subject = :implied
+        when '>'
+          stack = process_collection :close, stack, name: content
+          subject = :made
+        when ','
+          stack = process_component stack, name: content
+          subject = :implied
+        when '('
+          stack = process_subject stack, name: content, subject: subject
+          stack, i = process_constraints stack, chars: chars, index: i+1
+        else
+          reset = false
+          subject = :unmade
+        end
+
+        content = (reset) ? '' : content + chars[i]
+        i += 1
+      end
+
+      stack = process_end stack, name: content
+      stack.result
+    end
+
     # Process a collection
     #
     # This method either adds or updates a collection on +stack+ depending on
@@ -210,7 +226,7 @@ module Taipo
     # @api private
     def self.process_constraint(stack, raw:)
       n, v = parse_constraint raw
-      stack.add_constraint Taipo::TypeElement::Constraint.new(name: n, value: v)
+      stack.add_constraint name: n, value: v
     end
 
     # Process a series of constraints

data/lib/taipo/parser/stack.rb

@@ -112,8 +112,9 @@ module Taipo
       #
       # @since 1.4.0
       # @api private
-      def add_constraint(constraint)
-        self.last.push constraint
+      def add_constraint(name:, value:)
+        self.last.push Taipo::TypeElement::Constraint.new(name: name,
+                                                          value: value)
         self
       end
 

data/lib/taipo/parser/validater.rb

@@ -18,8 +18,7 @@ module Taipo
     #
     # The validater does not check whether the name represents a valid name in
     # the current context nor does it check whether the name complies with
-    # Ruby's requirements for names. Either situation will cause an exception
-    # to be raised by {Taipo::Check#check} or {Taipo::Check#review}.
+    # Ruby's requirements for names.
     #
     # One special case is where the name is left blank. The validater will
     # accept this as valid. {Taipo::Parser} will implictly add the name
@@ -32,7 +31,7 @@ module Taipo
     #
     # As noted above, duck types can be specified by using a blank name. Duck
     # types are really constraints (discussed in further detail below) on the
-    # class Object. While normally constraints need to be enclosed in
+    # class +Object+. While normally constraints need to be enclosed in
     # parentheses, if there is a blank name and only one method constraint, the
     # parentheses can be omitted. For defining duck types that respond to
     # multiple methods, the parentheses are required.
@@ -43,10 +42,10 @@ module Taipo
     #
     # It is possible to specify an 'optional' type by appending a question mark
     # to the name of the type. This shorthand functions similarly to defining a
-    # sum type with NilClass (the implementation of how optional types are
+    # sum type with +NilClass+ (the implementation of how optional types are
     # checked is slightly different, however; see {Taipo::TypeElement#match?}).
     # It is not possible to define an optional duck type. For that, either the
-    # implicit Object class should be specified (and then made optional), or a
+    # implicit +Object+ class should be specified (and then made optional), or a
     # sum type should be used.
     #
     # === Collections
@@ -62,8 +61,8 @@ module Taipo
     # definition for the child comes immediately after the opening angle
     # bracket.
     #
-    # If +Enumerator#each+ returns multiple values (eg. such as with Hash), the
-    # type definition for each value is delimited by a comma. It is optional
+    # If +Enumerator#each+ returns multiple values (eg. such as with +Hash+),
+    # the type definition for each value is delimited by a comma. It is optional
     # whether a space follows the comma.
     #
     # The type definition for a child element can contain all the components of
@@ -123,7 +122,7 @@ module Taipo
     # It's possible to approximate the enum idiom available in many languages
     # by creating a sum type consisting of Symbols. As a convenience, Taipo
     # parses these values as constraints on the Object class. In other words,
-    # +':foo|:bar'+ is really +'Object(val: :foo)|Object(val: :bar)'+.
+    # the +:foo|:bar+ is really +Object(val: :foo)|Object(val: :bar)+.
     #
     # @since 1.0.0
     module Validater

data/lib/taipo/result.rb

@@ -0,0 +1,102 @@
+require 'taipo/utilities'
+
+module Taipo
+
+  # A simple DSL for declaring type checks to run against the return values of
+  # specified instance methods
+  #
+  # {Taipo::Result} works by:
+  # 1. adding the {Taipo::Result::ClassMethods#result} method to the including
+  #    class;
+  # 2. prepending a module to the ancestor chain for the including class; and
+  # 3. defining a method on the ancestor with the same name as a particular
+  #    instance method on the class and using that method to intercept method
+  #    calls and check the return type.
+  #
+  # Because of how {Taipo::Result} makes the +result+ keyword available to
+  # classes, the documentation for this method is in
+  # {Taipo::Result::ClassMethods}.
+  #
+  # @since 1.5.0
+  module Result
+
+    # Add the {Taipo::Result::ClassMethods#result} method to the class including
+    # this module as well as prepend a module to the ancestor chain.
+    #
+    # @param base [Class] the class including this module
+    #
+    # @since 1.5.0
+    # @api private
+    def self.included(base)
+      base.extend ClassMethods
+      module_name = "#{base.class.name}Checker"
+      checker = const_defined?(module_name) ? const_get(module_name) :
+                                              const_set(module_name, Module.new)
+      base.prepend checker
+    end
+
+    # A helper module for holding the DSL methods
+    #
+    # @since 1.5.0
+    # @api private
+    module ClassMethods
+
+      # The DSL method used to declare a type check on the return value of a
+      # method. The intention is that a user will declare the type of result
+      # expected from a method by calling this method in the body of a class
+      # definition.
+      #
+      # For purposes of readability, the convention is that
+      # {Taipo::Result::ClassMethods#result} will be called near the beginning
+      # of the class definition but this is not a requirement and the user is
+      # free to call the method immediately before or after the relevant method
+      # definition.
+      #
+      # @param method_name [Symbol] the name of the instance method
+      # @param type [String] a type definition
+      #
+      # @since 1.5.0
+      # @api public
+      #
+      # @example
+      #   require 'taipo'
+      #
+      #   class A
+      #     include Taipo::Result
+      #
+      #     result :foo, 'String'
+      #     result :bar, 'Integer'
+      #
+      #     def foo(arg)
+      #       arg.to_s
+      #     end
+      #
+      #     def bar(arg)
+      #       arg.to_s
+      #     end
+      #   end
+      #
+      #   a = A.new
+      #   a.foo 'Hello world!'  #=> "Hello world!"
+      #   a.bar 42              #=> Taipo::TypeError
+      def result(method_name, type)
+        base = self
+        checker = const_get "#{base.class.name}Checker"
+        checker.class_eval do
+          define_method(method_name) do |*args, &block|
+            method_return_value = super(*args, &block)
+            if Taipo::Utilities.match?(object: method_return_value,
+                                       definition: type)
+              method_return_value
+            else
+              Taipo::Utilities.throw_error(object: method_return_value,
+                                           name: "#{base.name}##{method_name}",
+                                           definition: type,
+                                           result: true)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/taipo/type_element/children.rb

@@ -1,5 +1,3 @@
-require 'taipo/type_elements'
-
 module Taipo
   class TypeElement
 

data/lib/taipo/type_element/constraints.rb

@@ -1,5 +1,3 @@
-require 'taipo/type_element/constraint'
-
 module Taipo
   class TypeElement
 
@@ -11,7 +9,8 @@ module Taipo
 
       # Initialize a new set of {Taipo::TypeElement::Constraint}
       #
-      # @param els [Array<Taipo::TypeElement::Constraint>] the constraints
+      # @param constraints [Array<Taipo::TypeElement::Constraint>] the
+      #   constraints
       #
       # @since 1.4.0
       # @api private

data/lib/taipo/utilities.rb

@@ -1,3 +1,6 @@
+require 'taipo/exceptions'
+require 'taipo/parser'
+
 module Taipo
 
   # Utility methods for Taipo
@@ -6,6 +9,29 @@ module Taipo
   # @api private
   module Utilities
 
+    # Return a named variable from either an object or a binding
+    #
+    # @param name [String] the name of the variable
+    # @param object [Object] the object in which the variable may exist
+    # @param context [Binding] the binding in which the variable may exist
+    #
+    # @return [Object] the variable
+    #
+    # @raise [Taipo::NameError] if no variable with +name+ exists
+    #
+    # @since 1.5.0
+    # @api private
+    def self.extract_variable(name:, object:, context:)
+      if name[0] == '@' && object.instance_variable_defined?(name)
+        object.instance_variable_get name
+      elsif name[0] != '@' && context.local_variable_defined?(name)
+        context.local_variable_get name
+      else
+        msg = "Argument '#{name}' is not defined."
+        raise Taipo::NameError, msg
+      end
+    end
+
     # Check if a string is the name of an instance method
     #
     # @note All this does is check whether the given string begins with a hash
@@ -21,6 +47,27 @@ module Taipo
       str[0] == '#'
     end
 
+    # Check if an object matches a given type definition
+    #
+    # @param object [Object] the object to check
+    # @param definition [String] the type definiton to check against
+    #
+    # @return [Boolean] the result
+    #
+    # @raise [::TypeError] if +definition+ is not a String
+    # @raise [Taipo::SyntaxError] if the type definitions in +checks+ are
+    #   invalid
+    #
+    # @since 1.5.0
+    # @api private
+    def self.match?(object:, definition:)
+      msg = "The 'definition' argument must be of type String."
+      raise ::TypeError, msg unless definition.is_a? String
+
+      types = Taipo::Parser.parse definition
+      types.any? { |t| t.match? object }
+    end
+
     # Return the type definition for an object
     #
     # @note This assume that each element returned by Enumerator#each has the same
@@ -77,5 +124,37 @@ module Taipo
     def self.symbol?(str)
       str[0] == ':'
     end
+
+    # Throw an error with an appropriate message for a given object not matching
+    # a given type definition
+    #
+    # @param object [Object] the object that does not match +definition+
+    # @param name [String] the name of the object (with the code that originally
+    #   called the #check method)
+    # @param definition [String] the type definition that does not match +object+
+    # @param result [Boolean] whether this is being called in respect of a
+    #   return value (such as by {Taipo::Result::ClassMethods#result})
+    #
+    # @raise [Taipo::TypeError] the error
+    #
+    # @since 1.5.0
+    # @api private
+    def self.throw_error(object:, name:, definition:, result: false)
+      subject = (result) ? "The return value of #{name}" : "Object '#{name}'"
+
+      if Taipo::Utilities.instance_method? definition
+        msg = "#{subject} does not respond to #{definition}."
+      elsif Taipo::Utilities.symbol? definition
+        msg = "#{subject} is not equal to #{definition}."
+      elsif object.is_a? Enumerable
+        type_def = Taipo::Utilities.object_to_type_def object
+        msg = "#{subject} is #{type_def} but expected #{definition}."
+      else
+        class_name = object.class.name
+        msg = "#{subject} is #{class_name} but expected #{definition}."
+      end
+
+      raise Taipo::TypeError, msg
+    end
   end
-end
+end

data/lib/taipo/version.rb

@@ -1,3 +1,3 @@
 module Taipo
-  VERSION = "1.4.0"
+  VERSION = "1.5.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: taipo
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Michael Camilleri
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-01 00:00:00.000000000 Z
+date: 2018-06-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -136,6 +136,7 @@ files:
 - lib/taipo/parser/syntax_state.rb
 - lib/taipo/parser/validater.rb
 - lib/taipo/refinements.rb
+- lib/taipo/result.rb
 - lib/taipo/type_element.rb
 - lib/taipo/type_element/children.rb
 - lib/taipo/type_element/constraint.rb