taipo 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 80a49dd630a757254866642ae69f3fd46f8804ca
-  data.tar.gz: ac833851465c9174ffecdb1cd0c42e2f149bed75
+  metadata.gz: 5583e28b7b31de0e646bbdf2f03f274417946935
+  data.tar.gz: 5b9d14b293cabde611addc66b7857c2a16a46929
 SHA512:
-  metadata.gz: a89531bc4c8f93e77badf0b3c6ca411c5eaf6bc67dde11816f74de816d6eb394a031c27b3de0d3537ca3567afa4f8215d4ef38d05a1a84654defa38b347b0f7e
-  data.tar.gz: a18955f94b5744fc33c7739dac871fac1b94424d22f11119f16ee895dd3d7191206e5276eb9cf80df1064fb0b572c8f1126092c7fbcdf329a64198e4ad43c0a3
+  metadata.gz: b9c8e5d7fc2d9a419fb91cb82d063e2c4e294ba5b43677546557a133b9e0dbae420c3984f499381ae4e4d54157eb254fa0106720e6e44c2b271bacb34a97e487
+  data.tar.gz: 84aee96a5489147d14e7d2ed37ae66dbbbf8f7a6d9e12a365c4fb901160e91d6a58f6bbd6e5d59d03bbe3183b07030215fb5f0c5f74b644f28b88dbcddc3c885

data/README.md

@@ -1,7 +1,13 @@
+[![Gem Version](https://badge.fury.io/rb/taipo.svg)](https://badge.fury.io/rb/taipo) [![Inline docs](http://inch-ci.org/github/pyrmont/taipo.svg?branch=master)](http://inch-ci.org/github/pyrmont/taipo)
+
 # Taipo
 
 Taipo is a simple library for checking the types of variables.
 
+[Full documentation][rd] is available at RubyDoc.
+
+[rd]: http://www.rubydoc.info/gems/taipo/index
+
 ## Overview
 
 When we deal with variables in our code, we have certain expectations about what those variables can and can’t do.
@@ -14,18 +20,18 @@ 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`.
+Taipo provides two methods in the `Taipo::Check` module that we can mix into our classes: `#check` and `#review`.
 
 ### #check
 
-```
+```ruby
 require ‘taipo’
 
 class Foo
   include Taipo::Check
-  
+
   def double(val)
-    check types, val: ‘Integer’    
+    check types, val: ‘Integer’
     val * 2
   end
 end
@@ -37,14 +43,18 @@ 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.
 
+[More information about `#check`][rdc] is available in the documentation.
+
+[rdc]: http://www.rubydoc.info/gems/taipo/Taipo/Check#check-instance_method
+
 ### #review
 
-```
+```ruby
 require ‘taipo’
 
 class Foo
   include Taipo::Check
-  
+
   def add(x, y)
     errors = review types, x: ‘Integer’, y: ‘Integer’
     if errors.empty?
@@ -62,26 +72,56 @@ 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.
 
+[More information about `#review`][rdr] is available in the documentation.
+
+[rdr]: http://www.rubydoc.info/gems/taipo/Taipo/Check#review-instance_method
+
 ## Syntax
 
-Type definitions are passed as Strings with a straightforward syntax.
+Type definitions are written as Strings. Type definitions can consist of (1) names, (2) collections, (3) constraints and (4) sums.
+
+The information in this README is only meant as an introduction. [More information about the type definition syntax][rdv] is available in the documentation.
 
-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.
+[rdv]: http://www.rubydoc.info/gems/taipo/Taipo/Parser/Validater
 
+### Names
+
+The simplest case is to write the name of a class. For example, `’String’`. Inherited class names can also be used.
+
+```ruby
+check types, a: 'String', b: 'Numeric'
 ```
-'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'
+
+#### Duck Types
+
+It's possible to specify a duck type by writing the instance method (or methods) to which the object should respond.
+
+```ruby
+check types, a: '#to_s', b: '(#foo, #bar)'
+```
+
+### Collections
+
+Taipo can also check whether a variable has a collection of elements of the specified child type. A child type can consist of the same components as any other type (ie. a name, collection, constraint, sum).
+
+```ruby
+check types, a: 'Array<Integer>', b: 'Hash<Symbol, String>', c: 'Array<Array<Float>>'
+```
+
+### Constraints
+
+Constraints can be added to a type definition. Constraints consist of a list of one or more identifier-value pairs. Instance method names can also be in included.
+
+```ruby
+check types, a: 'Array(len: 5)', b: 'Integer(min: 0, max: 10)', c: 'String(format: /a{3}/)', d: 'String(val: "Hello world!")', e: 'Foo(#bar)'
+```
+
+### Sums
+
+Type definitions can be combined to form sum types. Sum types consist of two or more type definitions.
+
+```ruby
+check types, a: 'String|Float', b: 'Boolean|Array<String|Hash<Symbol,Point>|Array<String>>', c: 'Integer(max: 100)|Float(max: 100)'
 ```
 
 ## Requirements
@@ -90,21 +130,25 @@ 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. 
+Found a bug? I’d love to know about it. The best way is to report them in the [Issues section][ghi] on GitHub.
+
+[ghi]: https://github.com/pyrmont/taipo/issues
 
-## Contributions
+## Contributing
 
 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].
+Taipo began as, and remains primarily, an exercise to improve my programming skills. If Taipo has piqued your interest in adding type checks to Ruby, consider some of the other options, such as [Contracts][cnt], [Rtype][rty], [Rubype][rub] or [Sig][sig].
+
+[cnt]: https://github.com/egonSchiele/contracts.ruby
+[rty]: https://github.com/sputnikgugja/rtype
+[rub]: https://github.com/gogotanaka/Rubype
+[sig]: https://github.com/janlelis/sig
 
-[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
 
-# Licence
+Taipo is released into the public domain. See [LICENSE.md][lc] for more details.
 
-Taipo is released into the public domain. See LICENSE.md for more details.
+[lc]: https://github.com/pyrmont/taipo/blob/master/LICENSE.md

data/lib/taipo/parser/validater.rb

@@ -3,8 +3,95 @@ require 'taipo/parser/syntax_state'
 
 module Taipo
   module Parser
-    
+
     # A validater of Taipo type definitions
+    #
+    # Taipo's type definition syntax has four components: (1) names; (2)
+    # collections; (3) constraints; and (4) sums.
+    #
+    # === Names
+    #
+    #   'String', 'Numeric'
+    #
+    # A name should be the name of a class or a module.
+    #
+    # 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}.
+    #
+    # One special case is where the name is left blank. The validater will
+    # accept this as valid. {Taipo::Parser} will implictly add the name
+    # 'Object' when parsing the type definition. This allows a clean syntax for
+    # duck types (which are really constraints on the class Object).
+    #
+    # === Collections
+    #
+    #   'Array<Integer>', 'Hash<Symbol, String>', 'Array<Array<Float>>'
+    #
+    # A collection should be the type definiton for elements returned by
+    # +Enumerator#each+ (the child type) called on the collecting object (the
+    # parent type).
+    #
+    # A collection is demarcated by the angle brackets +<+ and +>+. These come
+    # immediately after the name of the parent (ie. without a space). The type
+    # 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
+    # whether a space follows the comma.
+    #
+    # The type definition for a child element can contain all the components of
+    # a type definition (ie. name, collection, constraint, sum) allowing for
+    # collections that contain collections and so on.
+    #
+    # === Constraints
+    #
+    #   'Array(len: 5)', 'Integer(min: 0, max: 10)', 'String(format: /a{3}/)',
+    #   'String(val: "Hello world!")', 'Foo(#bar)'
+    #
+    # A constraint should be a list of identifiers and values.
+    #
+    # A constraint is demarcated by parentheses (ie. +(+ and +)+). These come
+    # immediately after the name or collection (ie. without a space). The first
+    # identifier comes immediately after the opening parenthesis.
+    #
+    # An identifier and a value are separated by a colon (and an optional
+    # space). Multiple identifier-value pairs are delimited by a comma. It is
+    # optional whether a space follows the comma.
+    #
+    # The permitted identifiers and their values are as follows:
+    # - +format+: takes a regular expression demarcated by +/+
+    # - +len+: takes an integer
+    # - +max+: takes an integer
+    # - +min+: takes an integer
+    # - +val+: takes a number or a string demarcated by +"+
+    #
+    # The validater does not check whether the identifiers and values are
+    # acceptable, merely that they conform to the grammar.
+    # {Taipo::Parser.parse} will raise an exception when it parses the
+    # definition if the values are not acceptable for the relevant identifier.
+    # Similarly, while the repetition of an identifier is technically invalid,
+    # the exception will not be raised until {Taipo::Parser.parse} is called.
+    #
+    # One special case is where the identifier begins with a +#+. For this
+    # identifier, no value is provided and the constraint instead results in
+    # {Taipo::Check#check} and {Taipo::Check#review} checking whether the
+    # given object returns true for +Object#respond_to?+ with the identifier as
+    # the symbol.
+    #
+    # === Sums
+    #
+    #   'String|Float',
+    #   'Boolean|Array<String|Hash<Symbol,Point>|Array<String>>',
+    #   'Integer(max: 100)|Float(max: 100)'
+    #
+    # A sum is a combination of two or more type definitions.
+    #
+    # The sum comprises two or more type definitions, each separated by a bar
+    # (ie. +|+).
+    #
     # @since 1.0.0
     module Validater
 
@@ -12,8 +99,10 @@ module Taipo
       #
       # @param str [String] a type definition
       #
+      # @return [NilClass]
+      #
       # @raise [::TypeError] if +str+ is not a String
-      # @raise [Taipo::SyntaxError] if +str+ is not a valid type definition 
+      # @raise [Taipo::SyntaxError] if +str+ is not a valid type definition
       #
       # @since 1.0.0
       def self.validate(str)

data/lib/taipo/type_element/constraint.rb

@@ -72,7 +72,7 @@ module Taipo
           end
         when 'min'
           if arg.is_a? Numeric
-            arg <= @value
+            arg >= @value
           else
             arg.respond_to?('size') && arg.size >= @value
           end

data/lib/taipo/version.rb

@@ -1,3 +1,3 @@
 module Taipo
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

data/lib/taipo.rb

@@ -3,14 +3,30 @@ require 'taipo/check'
 require 'taipo/parser'
 
 # 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.
+#
+# 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 that can specify the type of the variable (including sum types)
+# and the types of any elements it contains, all subject to a given constraints
+# (see {Taipo::Parser::Validater} for the full syntax).
+#
+# As syntactic sugar, the {Taipo::Check} module also aliases +Kernel#binding+
+# with the keyword +types+. This allows the user to call {Taipo::Check#check}
+# and {Taipo::Check#review} by writing +check types, ...+ and
+# +review types, ...+ respectively.
+#
 # @since 1.0.0
-# @see https://github.com/pyrmont/shakushi
+# @see https://github.com/pyrmont/taipo
 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 
+  # @note All this does is check whether the given string begins with a hash
   #   symbol.
   #
   # @param str [String] the method name to check

data/taipo.gemspec

@@ -12,9 +12,11 @@ Gem::Specification.new do |spec|
   spec.summary       = %q{A simple library for checking the types of variables.}
   spec.description   = %q{Taipo provides a simple way to check your variables are what you think they are. With an easy to use syntax you can call a single method and pass expressive type definitions.}
   spec.homepage      = "https://github.com/pyrmont/taipo/"
+  spec.license       = "Unlicense"
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   spec.require_paths = ["lib"]
+  spec.required_ruby_version = '>= 2.4.0'
 
   spec.metadata['allowed_push_host'] = 'https://rubygems.org'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: taipo
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Michael Camilleri
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-01-18 00:00:00.000000000 Z
+date: 2018-01-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -124,7 +124,8 @@ files:
 - lib/taipo/version.rb
 - taipo.gemspec
 homepage: https://github.com/pyrmont/taipo/
-licenses: []
+licenses:
+- Unlicense
 metadata:
   allowed_push_host: https://rubygems.org
 post_install_message: 
@@ -135,7 +136,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="