Module: Taipo::Check

Defined in:
lib/taipo/check.rb

Overview

A simple DSL for declaring type checks to run against specified variables

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 TypeElement instances; and

  3. checking whether the argument’s value matches any of the instances of TypeElement in the array.

As syntactic sugar, the Check module will by default alias Kernel#binding with the keyword types. This allows the user to call #check by writing check types (with a similar syntax for #review). If the user does not want to alias, they can set alias= to false before including or extending Check.

Since:

  • 1.0.0

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.extended(extender) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Perform operations if this module is extended

This is the callback called by Ruby when a module is included. In this case, the callback will alias the method __types__ as types if Taipo.alias? returns true. @@alias is reset to true at the end of this method.

Parameters:

  • extender (Class|Module) —

    the class or module extending this module

Since:

  • 1.1.0



124
125
126
127
128
 
# File 'lib/taipo/check.rb', line 124

def self.extended(extender)
  extender.singleton_class.send(:alias_method, :types, :__types__) if
    Taipo.alias?
  Taipo.alias = true
end

.included(includer) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Perform operations if this module is included

This is the callback called by Ruby when a module is included. In this case, the callback will alias the method __types__ as types if Taipo.alias? returns true. @@alias is reset to true at the end of this method.

Parameters:

  • includer (Class|Module) —

    the class or module including this module

Since:

  • 1.1.0



141
142
143
144
 
# File 'lib/taipo/check.rb', line 141

def self.included(includer)
  includer.send(:alias_method, :types, :__types__) if Taipo.alias?
  Taipo.alias = true
end

Instance Method Details

#check(context, collect_invalids = false, **checks) ⇒ Array

Check whether the given arguments match the given type definition in the given context

Examples:

require '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!')   #=> Taipo::TypeError

Parameters:

  • context (Binding) —

    the context in which the arguments to be checked are defined

  • collect_invalids (Boolean) (defaults to: false) —

    whether to raise an exception for, or collect, an argument that doesn’t match its type definition

  • 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

Returns:

  • (Array) —

    the arguments which don’t match (ie. an empty array if all arguments match)

Raises:

  • (::TypeError) —

    if the context is not a Binding

  • (Taipo::SyntaxError) —

    if the type definitions in checks are invalid

  • (Taipo::TypeError) —

    if the arguments in checks don’t match the given type definition

Since:

  • 1.0.0



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/taipo/check.rb', line 76

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 = Taipo::Utilities.extract_variable(name: k,
                                            object: self,
                                            context: context)

    is_match = Taipo::Utilities.match? object: arg, definition: v

    unless collect_invalids || is_match
      Taipo::Utilities.throw_error object: arg, name: k, definition: v
    end

    (is_match) ? memo : memo.push(k)
  end
end

#review(context, **checks) ⇒ Array

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.

Parameters:

  • context (Binding) —

    the context in which the arguments to be checked are defined

  • 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

Returns:

  • (Array) —

    the arguments which don’t match (ie. an empty array if all arguments match)

Raises:

  • (::TypeError) —

    if the context is not a Binding

  • (Taipo::SyntaxError) —

    if the type definitions in checks are invalid

  • (Taipo::TypeError) —

    if the arguments in checks don’t match the given type definition

Since:

  • 1.0.0



109
110
111
 
# File 'lib/taipo/check.rb', line 109

def review(context, **checks)
  self.check(context, true, checks)
end