taipo 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 80a49dd630a757254866642ae69f3fd46f8804ca
+  data.tar.gz: ac833851465c9174ffecdb1cd0c42e2f149bed75
+SHA512:
+  metadata.gz: a89531bc4c8f93e77badf0b3c6ca411c5eaf6bc67dde11816f74de816d6eb394a031c27b3de0d3537ca3567afa4f8215d4ef38d05a1a84654defa38b347b0f7e
+  data.tar.gz: a18955f94b5744fc33c7739dac871fac1b94424d22f11119f16ee895dd3d7191206e5276eb9cf80df1064fb0b572c8f1126092c7fbcdf329a64198e4ad43c0a3

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle
+/.ruby-version
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/vendor/
+/tmp/
+*.swp

data/Gemfile

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

data/LICENSE.md

@@ -0,0 +1,9 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commerciaL, and by any means.
+
+In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.
+
+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 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.
+
+For more information, please refer to <http://unlicense.org/>

data/README.md

@@ -0,0 +1,110 @@
+# Taipo
+
+Taipo is a simple library for checking the types of variables.
+
+## Overview
+
+When we deal with variables in our code, we have certain expectations about what those variables can and can’t do.
+
+Taipo provides a simple way to make those expectations explicit. If an expectation isn’t met, Taipo can either raise an exception or return the problematic variables for us to handle.
+
+## Installation
+
+Run `gem install taipo` or add `gem 'taipo'` to your `Gemfile`.
+
+## Usage
+
+Taipo provides two methods that we can mix into our classes: `#check` and `#review`.
+
+### #check
+
+```
+require ‘taipo’
+
+class Foo
+  include Taipo::Check
+  
+  def double(val)
+    check types, val: ‘Integer’    
+    val * 2
+  end
+end
+
+foo = Foo.new
+foo.double 5      #=> 10
+foo.double ‘Oops’ #=> Taipo::TypeError
+```
+
+The method `#check` will raise an exception as soon as one of its arguments doesn’t match its type definition.
+
+### #review
+
+```
+require ‘taipo’
+
+class Foo
+  include Taipo::Check
+  
+  def add(x, y)
+    errors = review types, x: ‘Integer’, y: ‘Integer’
+    if errors.empty?
+      x + y
+    else
+      ‘Oops’
+    end
+  end
+end
+
+foo = Foo.new
+foo.add 4, 5      #=> 9
+foo.add 2, ‘OK’   #=> ‘Oops’
+```
+
+The method `#review` will put the invalid arguments into an array and return that to the user. If there are no errors, the array is empty.
+
+## Syntax
+
+Type definitions are passed as Strings with a straightforward syntax.
+
+The simplest case is to write the name of a class. For example, `’String’`. Taipo supports more complex type definitions should you need them. Here are some more examples.
+
+```
+'String'
+'Array<String>'
+'Hash<Symbol,String>'
+'String|Float'
+'Boolean|Array<String|Hash<Symbol,Point>|Array<String>>'
+'Array(len: 5)'
+'String(format: /woo/)'
+'String(#size)'
+'String(#size, #to_s)'
+'Integer(min: 1, max: 10)'
+'String(val: "This is a test.")'
+'#to_s'
+'#to_s|#to_i'
+```
+
+## Requirements
+
+Taipo has been tested with Ruby version 2.4.2.
+
+## Bugs
+
+Found a bug? I’d love to know about it. The best way is to report them on GitHub. 
+
+## Contributions
+
+If you’re interested in contributing to Taipo, feel free to fork and submit a pull request.
+
+## Colophon
+
+Taipo began as an exercise to improve my programming skills. If you want something more comprehensive, consider some of the other options, such as [Contracts][1], [Rtype][2], [Rubype][3] or [Sig][4].
+
+[1]: https://github.com/egonSchiele/contracts.ruby
+[2]: https://github.com/sputnikgugja/rtype
+[3]: https://github.com/gogotanaka/Rubype
+[4]: https://github.com/janlelis/sig
+
+# Licence
+
+Taipo is released into the public domain. See LICENSE.md for more details.

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |task|
+  task.libs << %w(test)
+  task.pattern = "test/test_*.rb"
+end
+
+task :default => :test

data/lib/taipo.rb

@@ -0,0 +1,39 @@
+require 'taipo/version'
+require 'taipo/check'
+require 'taipo/parser'
+
+# A library for checking the types of objects
+# 
+# @since 1.0.0
+# @see https://github.com/pyrmont/shakushi
+module Taipo
+
+  # 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 
+  #   symbol.
+  #
+  # @param str [String] the method name to check
+  #
+  # @return [Boolean] the result
+  #
+  # @since 1.0.0
+  # @api private
+  def self.instance_method?(str)
+    str[0] == '#'
+  end
+
+  # Convert an array into a type definition for the types of the elements in the array
+  #
+  # @param arg [Array] the array of elements
+  #
+  # @return [String] a type definition of the types in the array
+  #
+  # @since 1.0.0
+  # @api private
+  def self.child_types_string(arg)
+    child_types = Hash.new
+    arg.each { |a| child_types[a.class.name] = true }
+    '<' + child_types.keys.join('|') + '>'
+  end
+end

data/lib/taipo/cache.rb

@@ -0,0 +1,49 @@
+module Taipo
+  # A cache of Taipo::TypeElement created from parsed type definitions
+  #
+  # @since 1.0.0
+  # @api private
+  module Cache
+    
+    # The hash that acts as the cache
+    #
+    # @since 1.0.0
+    # @api private
+    @@Cache = {}
+
+    # Retrieve the Taipo::TypeElement object described by the type definition from the cache
+    #
+    # @param k [String] the type definition
+    #
+    # @return [Taipo::TypeElement] if the type definition has been saved
+    # @return [NilClass] if the type definition has not been saved
+    #
+    # @since 1.0.0
+    # @api private
+    def self.[](k)
+      @@Cache[k]
+    end
+
+    # 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
+    #
+    # @return [Taipo::TypeElement] the object to be saved
+    #
+    # @since 1.0.0
+    # @api private
+    def self.[]=(k,v)
+      @@Cache[k] = v
+    end
+
+    # Reset the cache
+    #
+    # @since 1.0.0
+    # @api private
+    def self.reset()
+      @@Cache = {}
+      return nil
+    end
+  end
+end

data/lib/taipo/check.rb

@@ -0,0 +1,117 @@
+require 'taipo/cache'
+require 'taipo/exceptions'
+require 'taipo/parser'
+require 'taipo/type_element'
+
+module Taipo
+
+  # A dedicated namespace for methods meant to be included by the user
+  #
+  # @since 1.0.0
+  module Check
+
+    # Syntactic sugar to allow a user to write +check types,...+ and +review
+    # types,...+
+    #
+    # @since 1.0.0
+    alias types binding
+
+    # Check whether the given arguments match the given type definition in the
+    # given context
+    #
+    # @param context [Binding] the context in which the arguments to be checked
+    #   are defined
+    # @param collect_invalids [Boolean] whether to raise an exception for, or
+    #   collect, an argument that doesn't match its type definition
+    # @param checks [Hash] the arguments to be checked written as +Symbol:
+    #   String+ pairs with the Symbol being the name of the argument and the
+    #   String being its type definition
+    #
+    # @return [Array] the arguments which don't match (ie. an empty array if
+    #   all arguments match)
+    #
+    # @raise [::TypeError] if the context is not a Binding
+    # @raise [Taipo::SyntaxError] if the type definitions in +checks+ are
+    #   invalid
+    # @raise [Taipo::TypeError] if the arguments in +checks+ don't match the
+    #   given type definition
+    #
+    # @since 1.0.0
+    #
+    # @example
+    #   require 'taipo/taipo'
+    #
+    #   class A
+    #     include Taipo::Check
+    #
+    #     def foo(str)
+    #       check types, str: 'String'
+    #       puts str
+    #     end
+    #
+    #     def bar(str)
+    #       check types, str: 'Integer'
+    #       puts str
+    #     end
+    #   end
+    #
+    #   a = A.new()
+    #   a.foo('Hello world!')     #=> "Hello world!"
+    #   a.bar('Goodbye world!')   #=> raise Taipo::TypeError
+    def check(context, collect_invalids = false, **checks)
+      msg = "The first argument to this method must be of type Binding."
+      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
+
+        is_match = types.any? { |t| t.match? arg }
+
+        unless collect_invalids || is_match
+          if Taipo::instance_method? v
+            msg = "Object '#{k}' does not respond to #{v}."
+          elsif arg.is_a? Enumerable
+            type_string = arg.class.name + Taipo.child_types_string(arg)
+            msg = "Object '#{k}' is #{type_string} but expected #{v}."
+          else
+            msg = "Object '#{k}' is #{arg.class.name} but expected #{v}."
+          end
+          raise Taipo::TypeError, msg
+        end
+
+        (is_match) ? memo : memo.push(k)
+      end
+    end
+
+    # Review whether the given arguments match the given type definition in the
+    # given context
+    #
+    # This is a convenience method for calling {#check} with +collect_invalids+
+    # set to true.
+    #
+    # @param context (see #check)
+    # @param checks (see #check)
+    #
+    # @return (see #check)
+    #
+    # @raise (see #check)
+    #
+    # @since 1.0.0
+    def review(context, **checks)
+      self.check(context, true, checks)
+    end
+  end
+end

data/lib/taipo/exceptions.rb

@@ -0,0 +1,6 @@
+require 'taipo/exceptions/name_error'
+require 'taipo/exceptions/syntax_error'
+require 'taipo/exceptions/type_error'
+
+module Taipo
+end

data/lib/taipo/exceptions/name_error.rb

@@ -0,0 +1,8 @@
+module Taipo
+
+  # An exception raised when an argument with a given name does not exist
+  #  
+  # @since 1.0.0
+  class NameError < ::NameError
+  end
+end

data/lib/taipo/exceptions/syntax_error.rb

@@ -0,0 +1,9 @@
+module Taipo
+  
+  # An exception raised when there is an error in the syntax of a type 
+  # definition
+  #
+  # @since 1.0.0
+  class SyntaxError < ::StandardError
+  end
+end

data/lib/taipo/exceptions/type_error.rb

@@ -0,0 +1,9 @@
+module Taipo
+  
+  # An exception raised when the type of a given argument does not match the
+  # given type definition
+  #
+  # @since 1.0.0
+  class TypeError < TypeError
+  end
+end

data/lib/taipo/parser.rb

@@ -0,0 +1,171 @@
+require 'taipo/exceptions'
+require 'taipo/parser/validater'
+require 'taipo/type_element'
+
+module Taipo
+
+  # A parser of Taipo type definitions
+  # @since 1.0.0
+  module Parser
+
+    # Return an array of Taipo::TypeElements based on +str+
+    #
+    # @param str [String] a type definition
+    #
+    # @return [Array<Taipo:TypeElement>] 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
+
+      content = ''
+      is_fallthrough = false
+      fallthroughs = [ '/', '"' ]
+      closing_symbol = ''
+      stack = Array.new
+      elements = Array.new
+      stack.push elements
+
+      str.each_char do |c|
+        c = '+' + c if is_fallthrough
+
+        case c
+        when '|'
+          next if content.empty? # Previous character must have been '>' or ')'.
+          el = Taipo::TypeElement.new name: content
+          content = ''
+          elements = stack.pop
+          elements.push el
+          stack.push elements
+        when '<'
+          el = Taipo::TypeElement.new name: content
+          content = ''
+          stack.push el
+          child_type = Taipo::TypeElement::ChildType.new
+          stack.push child_type
+          first_component = Array.new
+          stack.push first_component
+        when '>'
+          if content.empty? # Previous character must have been '>' or ')'.
+            last_component = stack.pop
+          else
+            el = Taipo::TypeElement.new name: content.strip
+            content = ''
+            last_component = stack.pop
+            last_component.push el
+          end
+          child_type = stack.pop
+          child_type.push last_component
+          parent_el = stack.pop
+          parent_el.child_type = child_type
+          elements = stack.pop
+          elements.push parent_el
+          stack.push elements
+        when '('
+          if content.empty? # Previous character must have been '>'.
+            elements = stack.pop
+            el = elements.pop
+            stack.push elements
+          else
+            el = Taipo::TypeElement.new name: content
+            content = ''
+          end
+          stack.push el
+          cst_collection = Array.new
+          stack.push cst_collection
+        when '#'
+          if bare_method_constraint? stack
+            content = content + '#'
+          else
+            cst = Taipo::TypeElement::Constraint.new
+            content = ''
+            cst_collection = stack.pop
+            cst_collection.push cst
+            stack.push cst_collection
+          end
+        when ':'
+          cst = Taipo::TypeElement::Constraint.new name: content.strip
+          content = ''
+          cst_collection = stack.pop
+          cst_collection.push cst
+          stack.push cst_collection
+        when ',' # We could be inside a collection or a set of constraints
+          if inside_collection? stack
+            previous_component = stack.pop
+            el = Taipo::TypeElement.new name: content.strip
+            content = ''
+            previous_component.push el
+            child_type = stack.pop
+            child_type.push previous_component
+            stack.push child_type
+            next_component = Array.new
+            stack.push next_component
+          else
+            cst_collection = stack.pop
+            cst = cst_collection.pop
+            cst.value = content.strip
+            content = ''
+            cst_collection.push cst
+            stack.push cst_collection
+          end
+        when ')'
+          cst_collection = stack.pop
+          cst = cst_collection.pop
+          cst.value = content.strip
+          content = ''
+          cst_collection.push cst
+          el = stack.pop
+          el.constraints = cst_collection
+          elements = stack.pop
+          elements.push el
+          stack.push elements
+        else
+          if is_fallthrough
+            c = c[1]
+            is_fallthrough = false if c == closing_symbol
+          elsif fallthroughs.any? { |f| f == c }
+            is_fallthrough = true
+            closing_symbol = c
+          end
+          content = content + c
+        end
+      end
+
+      unless content.empty?
+        el = Taipo::TypeElement.new name: content
+        elements = stack.pop
+        elements.push el
+        stack.push elements
+      end
+
+      stack.pop
+    end
+
+    # Check if the parser is inside a collection
+    #
+    # @param stack [Array] the stack of parsed elements
+    #
+    # @return [Boolean] the result
+    #
+    # @since 1.0.0
+    # @api private
+    def self.inside_collection?(stack)
+      stack[-2]&.class == Taipo::TypeElement::ChildType
+    end
+
+    # Check if this constraint is only a method
+    #
+    # @param stack [Array] the stack of parsed elements
+    #
+    # @return [Boolean] the result
+    #
+    # @since 1.0.0
+    # @api private
+    def self.bare_method_constraint?(stack)
+      stack[-2]&.class != Taipo::TypeElement
+    end
+  end
+end