eqq 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd093a7aa8c034327d463c56bfe120a8ecc48b52649ba7900491f05cc130cc38
-  data.tar.gz: 13f7ca2f2f40d9be41abd4408f5486b892f345347eb07eeb3f4d936c47cc92ab
+  metadata.gz: 22307661e329771fea7efcd7c282d17eda0130d0edb7aec3088257b21b73e4ba
+  data.tar.gz: ebc3138ade59e38f9bc34a42a93654d3a6ab1564a48b47df13d65ed7227c7488
 SHA512:
-  metadata.gz: 2e510f5313e0f890bf3c8277a413f937b0a26e2ba58e501591288556783bc5fffc944c23a1216ddf95308a111b06c6ac82557526d9f7de49ef9dbe7806f93bb6
-  data.tar.gz: 719905cbd2f71a388e13ca0427b7db49115513ce11395a436d8ef9fc43397c9c77cc408135862147bbfc3bac3fb36615332752f56ab28e4136bc74b8db3f97dd
+  metadata.gz: 16ae2b50b3c81291028946ec6ddb8753c06bc7fc472f29ab00b3f69b9136540f26079b8c23f983d0bf1482f93543744f2fae557bb0ef71f6fdcc73f115df9455
+  data.tar.gz: eced8529614ce3b1b8a4cc4087d58943bdbaabd0637a86bb10bcafe472ccdece82bae71d390fde84e95176318961e4ef74207ab4debc6e117411608f2e074176

data/README.md

@@ -3,9 +3,7 @@
 ![Build Status](https://github.com/kachick/eqq/actions/workflows/test_behaviors.yml/badge.svg?branch=main)
 [![Gem Version](https://badge.fury.io/rb/eqq.png)](http://badge.fury.io/rb/eqq)
 
-Pattern objects builder.
-
-`eqq` means `#===`
+Pattern objects builder
 
 ## Usage
 
@@ -14,7 +12,7 @@ Require Ruby 2.6 or later
 Add below code into your Gemfile
 
 ```ruby
-gem 'eqq', '0.0.2'
+gem 'eqq', '0.0.3'
 ```
 
 ### Overview
@@ -29,10 +27,94 @@ require 'eqq'
 pattern = Eqq.define do
   OR(AND(Float, 20..50), Integer)
 end
+
+p pattern #=> "OR(AND(Float, 20..50), Integer)"
 [4.2, 42, 42.0, 420].grep(pattern) #=> [42, 42.0, 420]
+
+inverted = Eqq.NOT(pattern)
+p inverted #=> "NOT(OR(AND(Float, 20..50), Integer))"
+[4.2, 42, 42.0, 420].grep(inverted) #=> [4.2]
+
+Eqq.SEND(:all?, pattern) === [4.2, 42, 42.0, 420] #=> false
+Eqq.SEND(:any?, pattern) === [4.2, 42, 42.0, 420] #=> true
+
+ret_in_case = (
+  case 42
+  when pattern
+    'Should be matched here! :)'
+  when inverted
+    'Should not be matched here! :<'
+  else
+    'Should not be matched here too! :<'
+  end
+)
+
+p ret_in_case #=> Should be matched here! :)
+
+ret_in_case = (
+  case 4.2
+  when pattern
+    'Should not be matched here! :<'
+  when inverted
+    'Should be matched here! :)'
+  else
+    'Should not be matched here too! :<'
+  end
+)
+
+p ret_in_case #=> Should be matched here! :)
 ```
 
+### Explanation
+
+All products can be called as `pattern === other`.
+
+This signature will fit in most Ruby code.
+
+* `case ~ when` syntax
+* Enumerable#grep
+* Enumerable#grep_v
+* Enumerable#all?
+* Enumerable#any?
+* Enumerable#none?
+* Enumerable#one?
+* Enumerable#slice_after
+* Enumerable#slice_before
+
+They can take this interface as the `pattern`.
+
+And you already saw. All of patterns can be mixed with other patterns as a parts.
+Reuse as you wish!
+
+Major builders as below
+
+* OR(*patterns) - Product returns true when matched even one pattern
+* AND(*patterns) - Product returns true when matched all patterns
+* NOT(pattern) - Product returns true when not matched the pattern
+* CAN(*method_names) - Product returns true when it has all of the methods (checked with `respond_to?`)
+* RESCUE(exception_class/module, pattern) - Product returns true when the pattern raises the exception
+* QUIET(*patterns) - Product returns true when all patterns did not raise any exception
+* EQ(object) - Product returns true when matched with `#==`
+* SAME(object) - Product returns true when matched with `#equal?`
+* SEND(name, pattern) - Basically provided for Enumerable
+* BOOLEAN() - Product returns true when matched to true or false
+* ANYTHING() - Product returns true, always true
+
+Minor builders as below, please see [API documents](https://kachick.github.io/eqq) for them.
+
+* NAND
+* NOR
+* XOR
+
+When you feel annoy to write `Eqq` in many place, please use `Eqq.define`.
+In the block scope, all builder methods can be used without receiver specifying.
+
+This gem provide [ruby/rbs](https://github.com/ruby/rbs) signature
+
 ## Links
 
 * [Repository](https://github.com/kachick/eqq)
-* [API documents](https://kachick.github.io/eqq)
+
+## NOTE
+
+* [`eqq` is the implementation name of `#===` in CRuby](https://github.com/ruby/ruby/blob/2a685da1fcd928530509e99f5edb4117bc377994/range.c#L1859)

data/lib/eqq.rb

@@ -4,19 +4,12 @@
 # Copyright (c) 2011 Kenichi Kamiya
 # Forked from https://github.com/kachick/validation at 2021
 
-require_relative 'eqq/buildable'
 require_relative 'eqq/version'
 
 module Eqq
-  extend Buildable
-
   class Error < StandardError; end
   class InvalidProductError < Error; end
 
-  class DSLScope
-    include Buildable
-  end
-
   class << self
     def valid?(object)
       case object
@@ -31,6 +24,7 @@ module Eqq
       end
     end
 
+    # @return [#===]
     def define(&block)
       pattern = DSLScope.new.instance_exec(&block)
       raise InvalidProductError unless valid?(pattern)
@@ -39,3 +33,13 @@ module Eqq
     end
   end
 end
+
+require_relative 'eqq/buildable'
+
+module Eqq
+  extend Buildable
+
+  class DSLScope
+    include Buildable
+  end
+end

data/lib/eqq/buildable.rb

@@ -5,15 +5,59 @@ module Eqq
   module Buildable
     extend self
 
+    class << self
+      INSPECTION_FALLBACK = 'UninspectableObject'
+
+      # @api private
+      # @return [String]
+      def safe_inspect(object)
+        String.try_convert(object.inspect) || INSPECTION_FALLBACK
+      rescue Exception
+        # This implementation used `RSpec::Support::ObjectFormatter::UninspectableObjectInspector` as a reference, thank you!
+        # ref: https://github.com/kachick/times_kachick/issues/97
+        singleton_class = class << object; self; end
+        begin
+          klass = singleton_class.ancestors.detect { |ancestor| !ancestor.equal?(singleton_class) }
+          native_object_id = '%#016x' % (object.__id__ << 1)
+          "#<#{klass}:#{native_object_id}>"
+        rescue Exception
+          INSPECTION_FALLBACK
+        end
+      end
+
+      # @api private
+      # @return [void]
+      def set_inspect(name:, product:, arguments:)
+        inspect = "#{name}(#{arguments.map { |argument| safe_inspect(argument) }.join(', ')})".freeze
+        product.define_singleton_method(:inspect) do
+          inspect
+        end
+      end
+
+      # @api private
+      # @return [void]
+      def validate_patterns(*patterns)
+        invalids = patterns.reject { |pattern| Eqq.valid?(pattern) }
+        invalid_inspections = invalids.map { |invalid| safe_inspect(invalid) }.join(', ')
+        raise ArgumentError, "given `#{invalid_inspections}` are invalid as pattern objects" unless invalids.empty?
+      end
+    end
+
     # @param pattern1 [Proc, Method, #===]
     # @param pattern2 [Proc, Method, #===]
     # @param patterns [Array<Proc, Method, #===>]
     # @return [Proc]
-    #   this lambda return true if match all patterns
     def AND(pattern1, pattern2, *patterns)
-      ->v {
-        [pattern1, pattern2, *patterns].all? { |pattern| pattern === v }
+      patterns = [pattern1, pattern2, *patterns].freeze
+      Buildable.validate_patterns(*patterns)
+
+      product = ->v {
+        patterns.all? { |pattern| pattern === v }
       }
+
+      Buildable.set_inspect(name: 'AND', product: product, arguments: patterns)
+
+      product
     end
 
     # @param pattern1 [Proc, Method, #===]
@@ -28,11 +72,16 @@ module Eqq
     # @param pattern2 [Proc, Method, #===]
     # @param patterns [Array<Proc, Method, #===>]
     # @return [Proc]
-    #   this lambda return true if match a any pattern
     def OR(pattern1, pattern2, *patterns)
-      ->v {
-        [pattern1, pattern2, *patterns].any? { |pattern| pattern === v }
+      patterns = [pattern1, pattern2, *patterns].freeze
+      Buildable.validate_patterns(*patterns)
+
+      product = ->v {
+        patterns.any? { |pattern| pattern === v }
       }
+      Buildable.set_inspect(name: 'OR', product: product, arguments: patterns)
+
+      product
     end
 
     # @param pattern1 [Proc, Method, #===]
@@ -45,54 +94,60 @@ module Eqq
 
     # @param pattern1 [Proc, Method, #===]
     # @param pattern2 [Proc, Method, #===]
-    # @param patterns [Array<Proc, Method, #===>]
     # @return [Proc]
-    def XOR(pattern1, pattern2, *patterns)
-      ->v {
-        [pattern1, pattern2, *patterns].one? { |pattern| pattern === v }
+    def XOR(pattern1, pattern2)
+      patterns = [pattern1, pattern2].freeze
+      Buildable.validate_patterns(*patterns)
+
+      product = ->v {
+        patterns.one? { |pattern| pattern === v }
       }
-    end
+      Buildable.set_inspect(name: 'XOR', product: product, arguments: patterns)
 
-    # @param pattern1 [Proc, Method, #===]
-    # @param pattern2 [Proc, Method, #===]
-    # @param patterns [Array<Proc, Method, #===>]
-    # @return [Proc]
-    def XNOR(pattern1, pattern2, *patterns)
-      NOT(XOR(pattern1, pattern2, *patterns))
+      product
     end
 
     # @param pattern [Proc, Method, #===]
     # @return [Proc]
     def NOT(pattern)
-      raise ArgumentError, 'wrong object for pattern' unless Eqq.valid?(pattern)
+      Buildable.validate_patterns(pattern)
+
+      product = ->v { !(pattern === v) }
 
-      ->v { !(pattern === v) }
+      Buildable.set_inspect(name: 'NOT', product: product, arguments: [pattern])
+
+      product
     end
 
-    # A pattern builder.
     # @param obj [#==]
     # @return [Proc]
     def EQ(obj)
-      ->v { obj == v }
+      ->v { obj == v }.tap do |product|
+        Buildable.set_inspect(name: 'EQ', product: product, arguments: [obj])
+      end
     end
 
     # @param obj [#equal?]
     # @return [Proc]
     def SAME(obj)
-      ->v { obj.equal?(v) }
+      ->v { obj.equal?(v) }.tap do |product|
+        Buildable.set_inspect(name: 'SAME', product: product, arguments: [obj])
+      end
     end
 
-    # @param message1 [Symbol, String]
-    # @param messages [Array<Symbol, String>]
+    # @param message1 [Symbol, String, #to_sym]
+    # @param messages [Array<Symbol, String, #to_sym>]
     # @return [Proc]
     def CAN(message1, *messages)
-      messages = begin
-        [message1, *messages].map(&:to_sym)
-      rescue NoMethodError
-        raise ArgumentError
-      end
+      messages = (
+        begin
+          [message1, *messages].map(&:to_sym).freeze
+        rescue NoMethodError
+          raise ArgumentError
+        end
+      )
 
-      ->v {
+      product = ->v {
         messages.all? { |message|
           begin
             v.respond_to?(message)
@@ -101,18 +156,20 @@ module Eqq
           end
         }
       }
+
+      Buildable.set_inspect(name: 'CAN', product: product, arguments: messages)
+
+      product
     end
 
     # @param pattern1 [Proc, Method, #===]
     # @param patterns [Array<Proc, Method, #===>]
     # @return [Proc]
     def QUIET(pattern1, *patterns)
-      patterns = [pattern1, *patterns]
-      unless patterns.all? { |pattern| Eqq.valid?(pattern) }
-        raise ArgumentError, 'wrong object for pattern'
-      end
+      patterns = [pattern1, *patterns].freeze
+      Buildable.validate_patterns(*patterns)
 
-      ->v {
+      product = ->v {
         patterns.all? { |pattern|
           begin
             pattern === v
@@ -123,16 +180,20 @@ module Eqq
           end
         }
       }
+
+      Buildable.set_inspect(name: 'QUIET', product: product, arguments: patterns)
+
+      product
     end
 
     # @param mod [Module]
     # @param pattern [Proc, Method, #===]
     # @return [Proc]
     def RESCUE(mod, pattern)
-      raise ArgumentError unless Eqq.valid?(pattern)
+      Buildable.validate_patterns(pattern)
       raise ArgumentError unless Module === mod
 
-      ->v {
+      product = ->v {
         begin
           pattern === v
           false
@@ -142,23 +203,41 @@ module Eqq
           false
         end
       }
+
+      Buildable.set_inspect(name: 'RESCUE', product: product, arguments: [mod, pattern])
+
+      product
     end
 
-    # @param name [Symbol, #to_sym]
+    # @param name [Symbol, String, #to_sym]
     # @param pattern [Proc, Method, #===]
     # @return [Proc]
     def SEND(name, pattern)
-      raise InvalidProductError unless Eqq.valid?(pattern)
+      name = (
+        begin
+          name.to_sym
+        rescue NoMethodError
+          raise ArgumentError
+        end
+      )
+      Buildable.validate_patterns(pattern)
 
-      ->v {
+      product = ->v {
         v.__send__(name, pattern)
       }
+
+      Buildable.set_inspect(name: 'SEND', product: product, arguments: [name, pattern])
+
+      product
     end
 
-    # @return [BasicObject]
+    ANYTHING = ->_v { true }
+    Buildable.set_inspect(name: 'ANYTHING', product: ANYTHING, arguments: [])
+    private_constant :ANYTHING
+
+    # @return [ANYTHING]
     def ANYTHING
-      # BasicObject.=== always passing
-      BasicObject
+      ANYTHING
     end
 
     BOOLEAN = OR(SAME(true), SAME(false))

data/lib/eqq/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Eqq
-  VERSION = '0.0.2'
+  VERSION = '0.0.3'
 end

data/sig/eqq.rbs

@@ -7,26 +7,44 @@ module Eqq
     def to_sym: -> Symbol
   end
 
+  interface _Inspectable
+    def inspect: () -> String
+  end
+
   module Buildable
-    # A pribate constant. Should not be used in your code.
-    BOOLEAN: ^(untyped object) -> bool
+    type patternable_lambda = ^(untyped object) -> bool
+    type product = patternable_lambda & _Inspectable
+
+    # A private constant. Should not be used in your code.
+    ANYTHING: product
+
+    # A private constant. Should not be used in your code.
+    BOOLEAN: product
+
+    # A private API. Should not be used in your code.
+    def self.safe_inspect: (untyped object)-> String
+
+    # A private API. Should not be used in your code.
+    def self.set_inspect: (name: String, product: patternable_lambda, arguments: Array[untyped])-> void
+
+    # A private API. Should not be used in your code.
+    def self.validate_patterns: (*untyped) -> void
 
     extend Buildable
-    def OR: (_Patternable, _Patternable, *_Patternable) -> ^(untyped object) -> bool
-    def AND: (_Patternable, _Patternable, *_Patternable) -> ^(untyped object) -> bool
-    def NAND: (_Patternable, _Patternable, *_Patternable) -> ^(untyped object) -> bool
-    def NOR: (_Patternable, _Patternable, *_Patternable) -> ^(untyped object) -> bool
-    def XOR: (_Patternable, _Patternable, *_Patternable) -> ^(untyped object) -> bool
-    def XNOR: (_Patternable, _Patternable, *_Patternable) -> ^(untyped object) -> bool
-    def NOT: (_Patternable) -> ^(untyped object) -> bool
-    def EQ: (untyped object) -> ^(untyped object) -> bool
-    def SAME: (untyped object) -> ^(untyped object) -> bool
-    def CAN: (_ToSym, *_ToSym) -> ^(untyped object) -> bool
-    def RESCUE: (Module, _Patternable) -> ^(untyped object) -> bool
-    def QUIET: (_Patternable, *_Patternable) -> ^(untyped object) -> bool
-    def SEND: (Symbol | String name, _Patternable) -> ^(untyped object) -> bool
-    def ANYTHING: () -> BasicObject
-    def BOOLEAN: () -> ^(untyped object) -> bool
+    def OR: (_Patternable, _Patternable, *_Patternable) -> product
+    def AND: (_Patternable, _Patternable, *_Patternable) -> product
+    def NAND: (_Patternable, _Patternable, *_Patternable) -> product
+    def NOR: (_Patternable, _Patternable, *_Patternable) -> product
+    def XOR: (_Patternable, _Patternable) -> product
+    def NOT: (_Patternable) -> product
+    def EQ: (untyped object) -> product
+    def SAME: (untyped object) -> product
+    def CAN: (_ToSym, *_ToSym) -> product
+    def RESCUE: (Module, _Patternable) -> product
+    def QUIET: (_Patternable, *_Patternable) -> product
+    def SEND: (Symbol | String name, _Patternable) -> product
+    def ANYTHING: () -> product
+    def BOOLEAN: () -> product
   end
 
   extend Buildable
@@ -37,13 +55,16 @@ module Eqq
   class InvalidProductError < Error
   end
 
-  # A pribate API. Should not be used in your code.
+  # A private API. Should not be used in your code.
   class DSLScope
     include Buildable
   end
 
   VERSION: String
 
+  # A private constant. Should not be used in your code.
+  INSPECTION_FALLBACK: String
+
   def self.valid?: (untyped object) -> bool
   def self.define:  { () -> _Patternable } -> _Patternable
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: eqq
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Kenichi Kamiya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-06-01 00:00:00.000000000 Z
+date: 2021-06-02 00:00:00.000000000 Z
 dependencies: []
 description: "    [4.2, 42, 42.0, 420].grep(Eqq.AND(Integer, 20..50)) #=> [42]\n"
 email: