kind 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d3ff3a2a9d5b61087a96cf0255208086b5338f2a5f5ccb4ca609a9c8cff01e5
-  data.tar.gz: 10d77db1c01fb6990056fbb1b3a2dde463b8627af1f5aa415b7b11a89b76c367
+  metadata.gz: 0ebe119486837b90cdb9bd3c61a7d429d218608c0a84b19c94dd9d752909b194
+  data.tar.gz: b881aa36c0c9611eaa755f1cf99a2cff3c320975450a8136eef244de612ba755
 SHA512:
-  metadata.gz: ef9bd5cfb51763cb15690e232e60b474c6f958f5d2de7faab9d5688ce1f9e9b74c529b2bc2fbae39082e7bc0ea13b5d95038d6fd488f0a8d96d576e4843eb5c4
-  data.tar.gz: 515db015436abfe14cc392d46cdb41e8590af11c1d5e8e12466a4d85bfcd8681759e40f20ffbd9bac44a859a9b658e37c9218f2eec9bcc9118f68d3f755b8c56
+  metadata.gz: 27fd2b57f56612086698768b584e5d26641ad2f568d023b0ef78a7ac12ea0333dfeadf05f2af69d496448e04b2c396782a3a95f17a93cf92b995ce3d5677a986
+  data.tar.gz: 14a9f90efd784f353cab0fd174b6bc6d715fc0905ff79d38c692eeacf41e43fac2404b8c40f8381e4e201f9bba14c529196c192aa3acec411b7e163b1864077d

data/README.md

@@ -26,6 +26,10 @@ One of the goals of this project is to do simple type checking like `"some strin
   - [Special type checkers](#special-type-checkers)
     - [Kind.of](#kindof)
     - [Kind.is](#kindis)
+- [Kind::Undefined](#kindundefined)
+- [Kind::Optional](#kindoptional)
+  - [Kind::Optional[] and Kind::Optional#then](#kindoptional-and-kindoptionalthen)
+  - [Kind::Optional#try](#kindoptionaltry)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
@@ -274,6 +278,103 @@ The list of types (classes and modules) available to use with `Kind.of.*` or `Ki
 
 [⬆️ Back to Top](#table-of-contents-)
 
+## Kind::Undefined
+
+The [`Kind::Undefined`](https://github.com/serradura/kind/blob/834f6b8ebdc737de8e5628986585f30c1a5aa41b/lib/kind/undefined.rb) constant is used as the default argument of type checkers. This is necessary [to know if no arguments were passed to the type check methods](https://github.com/serradura/kind/blob/834f6b8ebdc737de8e5628986585f30c1a5aa41b/lib/kind.rb#L45-L48). But, you can use it in your codebase too, especially if you need to distinguish the usage of `nil` as a method argument.
+
+If you are interested, check out [the tests](https://github.com/serradura/kind/blob/834f6b8ebdc737de8e5628986585f30c1a5aa41b/test/kind/undefined_test.rb) to understand its methods.
+
+[⬆️ Back to Top](#table-of-contents-)
+
+## Kind::Optional
+
+The `Kind::Optional` is used when a series of computations (in a chain of map callings) could return `nil` or `Kind::Undefined` at any point.
+
+```ruby
+optional =
+  Kind::Optional.new(2)
+                .map { |value| value * 2 }
+                .map { |value| value * 2 }
+
+puts optional.value # 8
+puts optional.some? # true
+puts optional.none? # false
+puts optional.value_or(0) # 8
+puts optional.value_or { 0 } # 8
+
+#################
+# Returning nil #
+#################
+
+optional =
+  Kind::Optional.new(3)
+                .map { nil }
+                .map { |value| value * 3 }
+
+puts optional.value # nil
+puts optional.some? # false
+puts optional.none? # true
+puts optional.value_or(0) # 0
+puts optional.value_or { 0 } # 0
+
+#############################
+# Returning Kind::Undefined #
+#############################
+
+optional =
+  Kind::Optional.new(4)
+                .map { Kind::Undefined }
+                .map { |value| value * 4 }
+
+puts optional.value # Kind::Undefined
+puts optional.some? # false
+puts optional.none? # true
+puts optional.value_or(1) # 1
+puts optional.value_or { 1 } # 1
+```
+
+### Kind::Optional[] and Kind::Optional#then
+
+You can use `Kind::Option[]` (brackets) instead of the `.new` to transform values in a `Kind::Optional`. Another alias is `.then` to the `.map` method.
+
+```ruby
+result =
+  Kind::Optional[5]
+    .then { |value| value * 5 }
+    .then { |value| value + 17 }
+    .value_or(0)
+
+puts result # 42
+```
+
+### Kind::Optional#try
+
+If you don't want to use a map to access the value, you could use the `#try` method to access it. So, if the value wasn't `nil` or `Kind::Undefined`, it will be returned.
+
+```ruby
+p Kind::Optional['foo'].try(:upcase) # "FOO"
+
+p Kind::Optional['bar'].try { |value| value.upcase } # "BAR"
+
+#############
+# Nil value #
+#############
+
+p Kind::Optional[nil].try(:upcase) # nil
+
+p Kind::Optional[nil].try { |value| value.upcase } # nil
+
+#########################
+# Kind::Undefined value #
+#########################
+
+p Kind::Optional[Kind::Undefined].try(:upcase) # nil
+
+p Kind::Optional[Kind::Undefined].try { |value| value.upcase } # nil
+```
+
+[⬆️ Back to Top](#table-of-contents-)
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/kind/checker.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Kind
+  module Checker
+    def class?(value)
+      Kind::Is.(__kind, value)
+    end
+
+    def instance?(value)
+      value.is_a?(__kind)
+    end
+
+    def or_nil(value)
+      return value if instance?(value)
+    end
+  end
+
+  private_constant :Checker
+end

data/lib/kind/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Kind
+  class Error < TypeError
+    def initialize(klass, object)
+      super("#{object.inspect} expected to be a kind of #{klass}")
+    end
+  end
+end

data/lib/kind/is.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Kind
+  module Is
+    def self.call(expected, value)
+      expected_mod = Kind::Of.Module(expected)
+      mod = Kind::Of.Module(value)
+
+      mod <= expected_mod || false
+    end
+
+    def self.Class(value)
+      value.is_a?(::Class)
+    end
+
+    def self.Module(value)
+      value == ::Module || (value.is_a?(::Module) && !self.Class(value))
+    end
+  end
+end

data/lib/kind/of.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Kind
+  module Of
+    def self.call(klass, object, name: nil)
+      return object if object.is_a?(klass)
+
+      raise Kind::Error.new((name || klass.name), object)
+    end
+
+    def self.Class(object = Undefined)
+      return Class if object == Undefined
+
+      self.call(::Class, object)
+    end
+
+    const_set(:Class, ::Module.new do
+      extend Checker
+
+      def self.__kind; ::Class; end
+
+      def self.class?(value); Kind::Is.Class(value); end
+
+      def self.instance?(value); class?(value); end
+    end)
+
+    def self.Module(object = Undefined)
+      return Module if object == Undefined
+
+      self.call(::Module, object)
+    end
+
+    const_set(:Module, ::Module.new do
+      extend Checker
+
+      def self.__kind; ::Module; end
+
+      def self.class?(value); Kind::Is.Module(value); end
+
+      def self.instance?(value); class?(value); end
+    end)
+  end
+end

data/lib/kind/optional.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Kind
+  class Optional
+    self.singleton_class.send(:alias_method, :[], :new)
+
+    IsNone = -> value { value == nil || value == Undefined }
+
+    attr_reader :value
+
+    def initialize(arg)
+      @value = arg.is_a?(Kind::Optional) ? arg.value : arg
+    end
+
+    INVALID_DEFAULT_ARG = 'the default value must be defined as an argument or block'.freeze
+
+    def value_or(default = Undefined, &block)
+      return @value if some?
+
+      if default == Undefined && !block
+        raise ArgumentError, INVALID_DEFAULT_ARG
+      else
+        IsNone.(default) ? block.call : default
+      end
+    end
+
+    def none?
+      @none ||= IsNone.(@value)
+    end
+
+    def some?
+      !none?
+    end
+
+    def map(&fn)
+      return self if none?
+
+      self.class.new(fn.call(@value))
+    end
+
+    alias_method :then, :map
+
+    def try(method_name = Undefined, &block)
+      fn = method_name == Undefined ? block : Kind.of.Symbol(method_name).to_proc
+
+      unless IsNone.(value)
+        result = fn.call(value)
+
+        return result unless IsNone.(result)
+      end
+    end
+
+    private_constant :IsNone, :INVALID_DEFAULT_ARG
+  end
+end

data/lib/kind/types.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Kind
+  module Types
+    extend self
+
+    COLONS = '::'.freeze
+
+    KIND_OF = <<-RUBY
+      def self.%{method_name}(object = Undefined, options = {})
+        default = options[:or]
+
+        return Kind::Of::%{kind_name} if object == Undefined && default.nil?
+
+        Kind::Of.(::%{kind_name}, (object || default), name: "%{kind_name}".freeze)
+      end
+    RUBY
+
+    KIND_IS = <<-RUBY
+      def self.%{method_name}(value = Undefined)
+        return Kind::Is::%{kind_name} if value == Undefined
+
+        Kind::Is.(::%{kind_name}, value)
+      end
+    RUBY
+
+    private_constant :KIND_OF, :KIND_IS, :COLONS
+
+    def add(kind, name: nil)
+      kind_name = Kind.of.Module(kind).name
+      checker = name ? Kind::Of.(String, name) : kind_name
+
+      case
+      when checker.include?(COLONS)
+        add_kind_with_namespace(checker, method_name: name)
+      else
+        add_root(checker, kind_name, method_name: name, create_kind_is_mod: false)
+      end
+    end
+
+    private
+
+      def add_root(checker, kind_name, method_name:, create_kind_is_mod:)
+        root_checker = method_name ? method_name : checker
+        root_kind_name = method_name ? method_name : kind_name
+
+        add_kind(root_checker, root_kind_name, Kind::Of, Kind::Is, create_kind_is_mod)
+      end
+
+      def add_kind_with_namespace(checker, method_name:)
+        raise NotImplementedError if method_name
+
+        const_names = checker.split(COLONS)
+        const_names.each_with_index do |const_name, index|
+          if index == 0
+            add_root(const_name, const_name, method_name: nil, create_kind_is_mod: true)
+          else
+            add_node(const_names, index)
+          end
+        end
+      end
+
+      def add_node(const_names, index)
+        namespace = const_names[0..(index-1)]
+        namespace_name = namespace.join(COLONS)
+
+        kind_of_mod = Kind::Of.const_get(namespace_name)
+        kind_is_mod = Kind::Is.const_get(namespace_name)
+
+        checker = const_names[index]
+        kind_name = const_names[0..index].join(COLONS)
+
+        add_kind(checker, kind_name, kind_of_mod, kind_is_mod, true)
+      end
+
+      def add_kind(checker, kind_name, kind_of_mod, kind_is_mod, create_kind_is_mod)
+        params = { method_name: checker, kind_name: kind_name }
+
+        unless kind_of_mod.respond_to?(checker)
+          kind_checker = ::Module.new { extend Checker }
+          kind_checker.module_eval("def self.__kind; #{kind_name}; end")
+
+          kind_of_mod.instance_eval(KIND_OF % params)
+          kind_of_mod.const_set(checker, kind_checker)
+        end
+
+        unless kind_is_mod.respond_to?(checker)
+          kind_is_mod.instance_eval(KIND_IS % params)
+          kind_is_mod.const_set(checker, Module.new) if create_kind_is_mod
+        end
+      end
+  end
+end

data/lib/kind/undefined.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Kind
+  Undefined = Object.new.tap do |undefined|
+    def undefined.inspect
+      @inspect ||= 'Undefined'.freeze
+    end
+
+    def undefined.to_s
+      inspect
+    end
+
+    def undefined.clone
+      self
+    end
+
+    def undefined.dup
+      clone
+    end
+
+    def undefined.default(value, default)
+      return self if value != self
+
+      default.respond_to?(:call) ? default.call : default
+    end
+  end
+end

data/lib/kind/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kind
-  VERSION = '1.1.0'
+  VERSION = '1.2.0'
 end

data/lib/kind.rb

@@ -1,177 +1,15 @@
 # frozen_string_literal: true
 
 require 'kind/version'
+require 'kind/undefined'
+require 'kind/optional'
+require 'kind/error'
+require 'kind/is'
+require 'kind/checker'
+require 'kind/of'
+require 'kind/types'
 
 module Kind
-  Undefined = Object.new
-
-  class Error < TypeError
-    def initialize(klass, object)
-      super("#{object.inspect} expected to be a kind of #{klass}")
-    end
-  end
-
-  module Is
-    def self.call(expected, value)
-      expected_mod = Kind::Of.Module(expected)
-      mod = Kind::Of.Module(value)
-
-      mod <= expected_mod || false
-    end
-
-    def self.Class(value)
-      value.is_a?(::Class)
-    end
-
-    def self.Module(value)
-      value == ::Module || (value.is_a?(::Module) && !self.Class(value))
-    end
-  end
-
-  module Checker
-    def class?(value)
-      Kind::Is.(__kind, value)
-    end
-
-    def instance?(value)
-      value.is_a?(__kind)
-    end
-
-    def or_nil(value)
-      return value if instance?(value)
-    end
-  end
-
-  module Of
-    def self.call(klass, object, name: nil)
-      return object if object.is_a?(klass)
-
-      raise Kind::Error.new((name || klass.name), object)
-    end
-
-    def self.Class(object = Undefined)
-      return Class if object == Undefined
-
-      self.call(::Class, object)
-    end
-
-    const_set(:Class, ::Module.new do
-      extend Checker
-
-      def self.__kind; ::Class; end
-
-      def self.class?(value); Kind::Is.Class(value); end
-
-      def self.instance?(value); class?(value); end
-    end)
-
-    def self.Module(object = Undefined)
-      return Module if object == Undefined
-
-      self.call(::Module, object)
-    end
-
-    const_set(:Module, ::Module.new do
-      extend Checker
-
-      def self.__kind; ::Module; end
-
-      def self.class?(value); Kind::Is.Module(value); end
-
-      def self.instance?(value); class?(value); end
-    end)
-  end
-
-  module Types
-    extend self
-
-    COLONS = '::'.freeze
-
-    KIND_OF = <<-RUBY
-      def self.%{method_name}(object = Undefined, options = {})
-        default = options[:or]
-
-        return Kind::Of::%{kind_name} if object == Undefined && default.nil?
-
-        Kind::Of.(::%{kind_name}, (object || default), name: "%{kind_name}".freeze)
-      end
-    RUBY
-
-    KIND_IS = <<-RUBY
-      def self.%{method_name}(value = Undefined)
-        return Kind::Is::%{kind_name} if value == Undefined
-
-        Kind::Is.(::%{kind_name}, value)
-      end
-    RUBY
-
-    private_constant :KIND_OF, :KIND_IS, :COLONS
-
-    def add(kind, name: nil)
-      kind_name = Kind.of.Module(kind).name
-      checker = name ? Kind::Of.(String, name) : kind_name
-
-      case
-      when checker.include?(COLONS)
-        add_kind_with_namespace(checker, method_name: name)
-      else
-        add_root(checker, kind_name, method_name: name, create_kind_is_mod: false)
-      end
-    end
-
-    private
-
-      def add_root(checker, kind_name, method_name:, create_kind_is_mod:)
-        root_checker = method_name ? method_name : checker
-        root_kind_name = method_name ? method_name : kind_name
-
-        add_kind(root_checker, root_kind_name, Kind::Of, Kind::Is, create_kind_is_mod)
-      end
-
-      def add_kind_with_namespace(checker, method_name:)
-        raise NotImplementedError if method_name
-
-        const_names = checker.split(COLONS)
-        const_names.each_with_index do |const_name, index|
-          if index == 0
-            add_root(const_name, const_name, method_name: nil, create_kind_is_mod: true)
-          else
-            add_node(const_names, index)
-          end
-        end
-      end
-
-      def add_node(const_names, index)
-        namespace = const_names[0..(index-1)]
-        namespace_name = namespace.join(COLONS)
-
-        kind_of_mod = Kind::Of.const_get(namespace_name)
-        kind_is_mod = Kind::Is.const_get(namespace_name)
-
-        checker = const_names[index]
-        kind_name = const_names[0..index].join(COLONS)
-
-        add_kind(checker, kind_name, kind_of_mod, kind_is_mod, true)
-      end
-
-      def add_kind(checker, kind_name, kind_of_mod, kind_is_mod, create_kind_is_mod)
-        params = { method_name: checker, kind_name: kind_name }
-
-        unless kind_of_mod.respond_to?(checker)
-          kind_checker = ::Module.new { extend Checker }
-          kind_checker.module_eval("def self.__kind; #{kind_name}; end")
-
-          kind_of_mod.instance_eval(KIND_OF % params)
-          kind_of_mod.const_set(checker, kind_checker)
-        end
-
-        unless kind_is_mod.respond_to?(checker)
-          kind_is_mod.instance_eval(KIND_IS % params)
-          kind_is_mod.const_set(checker, Module.new) if create_kind_is_mod
-        end
-      end
-  end
-
   def self.is; Is; end
   def self.of; Of; end
 
@@ -252,6 +90,4 @@ module Kind
       end
     end)
   end
-
-  private_constant :Checker
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kind
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Rodrigo Serradura
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-04-09 00:00:00.000000000 Z
+date: 2020-04-12 00:00:00.000000000 Z
 dependencies: []
 description: Basic type system for Ruby (free of dependencies).
 email:
@@ -28,6 +28,13 @@ files:
 - bin/setup
 - kind.gemspec
 - lib/kind.rb
+- lib/kind/checker.rb
+- lib/kind/error.rb
+- lib/kind/is.rb
+- lib/kind/of.rb
+- lib/kind/optional.rb
+- lib/kind/types.rb
+- lib/kind/undefined.rb
 - lib/kind/version.rb
 homepage: https://github.com/serradura/kind
 licenses: