data-option 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c482aa6857657bf2abcfbd51ef9bf19f485c2096645301a61a1b3391573f0bd4
+  data.tar.gz: 950af8e9f4b3fceec8c1dad184597a821e3e6094961bf352d31730eb627250ce
+SHA512:
+  metadata.gz: 972535d4f3b0c310ef247a680c6cd47b7e7041285b1a8a46d3af46f91022e4c42e9d3773ef814478db32ae6e0d4c4bc43a1f64283eb7a4e3b6ba76ba9f647a87
+  data.tar.gz: 93fb7a298300733845dbfec34099bfde13dd6f084cceccd281fad62fc204438f903c25a1868171e3db0836503125f133e0b989ea0fa17d95af736f894f606397

data/.rubocop.yml

@@ -0,0 +1,58 @@
+plugins:
+  - rubocop-minitest
+  - rubocop-rake
+
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+
+Bundler/GemFilename:
+  Enabled: false
+
+Layout/SpaceInsideHashLiteralBraces:
+  EnforcedStyle: no_space
+
+Lint/AmbiguousOperatorPrecedence:
+  Enabled: false
+
+Lint/BinaryOperatorWithIdenticalOperands:
+  Enabled: false
+
+Lint/SuppressedException:
+  Enabled: false
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/MethodLength:
+  Max: 42
+
+Minitest/MultipleAssertions:
+  Max: 6
+
+Naming/FileName:
+  Enabled: false
+
+Naming/MethodName:
+  Enabled: false
+
+Naming/RescuedExceptionsVariableName:
+  Enabled: false
+
+Style/Alias:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/MixinUsage:
+  Enabled: false
+
+Style/NumberedParametersLimit:
+  Max: 9
+
+Style/RescueStandardError:
+  Enabled: false

data/LICENSE.txt

@@ -0,0 +1,18 @@
+Copyright (c) Shannon Skipper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+  
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+   
+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.

data/README.md

@@ -0,0 +1,291 @@
+# Data::Option
+
+This gem provides a `None` and `Some` with methods for creating, matching, and transforming optional values with Rust-like semantics.
+
+## Installation
+
+```bash
+bundle add data-option
+```
+
+If you're not using Bundler, install the gem with:
+
+```bash
+gem install data-option
+```
+
+## Usage
+
+### Basic Example
+
+To use `Some[value]` and `None[]`, first `include Data::Option`.
+
+```ruby
+require 'data/option'
+
+include Data::Option
+
+def checked_division(dividend, divisor)
+  if divisor.zero?
+    None[]
+  else
+    Some[dividend / divisor]
+  end
+end
+
+def try_division(dividend, divisor)
+  case checked_division(dividend, divisor)
+  in None
+    puts "#{dividend} / #{divisor} failed!"
+  in Some(quotient)
+    puts "#{dividend} / #{divisor} = #{quotient}"
+  end
+end
+
+try_division(4, 2)
+# >> 4 / 2 = 2
+try_division(1, 0)
+# >> 1 / 0 failed!
+```
+
+### Creating an Option Value
+
+A `Some` or `None` can be created with multiple syntaxes:
+
+```ruby
+require 'data/option'
+
+include Data::Option
+
+Some[42]      # => Some[42]
+None[]        # => None
+
+Some.new(42)  # => Some[42]
+None.instance # => None
+```
+
+Kernel#Option creates an Option from any value:
+
+```ruby
+require 'data/option'
+
+Option(42)       # => Some[42]
+Option(false)    # => Some[false]
+Option(nil)      # => None
+```
+
+The equivalent class method `Option.from`:
+
+```ruby
+require 'data/option'
+
+# Same behavior as the Kernel method
+Option.from(42)    # => Some[42]
+Option.from(false) # => Some[false]
+Option.from(nil)   # => None
+```
+
+Enable Object#to_option via refinements:
+
+```ruby
+require 'data/option'
+
+using Data::Option::Refinement
+
+42.to_option    # => Some[42]
+false.to_option # => Some[false]
+nil.to_option   # => None
+
+42.to_option.map(&:succ)   # => Some[43]
+nil.to_option.map(&:succ)  # => None
+```
+
+### Predicates
+
+Check the state of your Option values with predicate methods:
+
+```ruby
+require 'data/option'
+
+include Data::Option
+
+some = Some[42]
+none = None[]
+
+some.some? # => true
+some.none? # => false
+none.some? # => false
+none.none? # => true
+
+Some[42].some_and?(&:even?)  # => true (value exists and is even)
+Some[41].some_and?(&:even?)  # => false (value exists but isn't even)
+None[].some_and?(&:even?)    # => false (no value to check)
+
+Some[42].none_or?(&:even?)   # => true (either None or predicate is true)
+Some[41].none_or?(&:even?)   # => false (has value but predicate is false)
+None[].none_or? { false }    # => true (None satisfies this predicate)
+```
+
+### Unwrapping
+
+Extract values from an Option safely:
+
+```ruby
+require 'data/option'
+
+include Data::Option
+
+some = Some[42]
+none = None[]
+
+some.unwrap  # => 42
+none.unwrap  #!> None::UnwrapError
+
+some.unwrap_or(0)  # => 42
+none.unwrap_or(0)  # => 0
+
+some.unwrap_or_else { rand(100) }  # => 42
+none.unwrap_or_else { rand(100) }  # => some random number
+
+some.expect('Should contain value')  # => 42
+none.expect('Missing expected value')  #!> None::UnwrapError
+```
+
+### Enumeration and Transformation
+
+Map, filter, and transform Option values:
+
+```ruby
+require 'data/option'
+
+include Data::Option
+
+Some[42].each { |value| puts value }  # prints 42
+None[].each { |value| puts value }    # no output
+
+Some[42].map { |n| n + 1 }  # => Some[43]
+None[].map { |n| n + 1 }    # => None
+
+Some[42].filter(&:even?)    # => Some[42]
+Some[41].filter(&:even?)    # => None
+None[].filter { true }      # => None
+
+Some[42].flat_map { |n| Some[n + 1] }  # => Some[43]
+Some[42].flat_map { |_| None[] }       # => None
+None[].flat_map { |n| Some[n + 1] }    # => None
+
+Some[Some[42]].flatten  # => Some[42]
+Some[None[]].flatten    # => None
+Some[42].flatten        # => Some[42]
+None[].flatten          # => None
+
+Some[42].map_or(0) { |n| n + 1 }  # => 43
+None[].map_or(0) { |n| n + 1 }    # => 0
+
+Some[42].map_or_else(-> { rand(100) }) { |n| n + 1 }  # => 43
+None[].map_or_else(-> { rand(100) }) { |n| n + 1 }    # => random number
+```
+
+### Logical Operations
+
+Combine Option values with logical operations:
+
+```ruby
+require 'data/option'
+
+include Data::Option
+
+Some[1].and(Some[2])  # => Some[2]
+Some[1].and(None[])   # => None
+None[].and(Some[1])   # => None
+None[].and(None[])    # => None
+
+Some[1].and_then { |n| Some[n + 1] }  # => Some[2]
+Some[1].and_then { |_| None[] }       # => None
+None[].and_then { |n| Some[n + 1] }   # => None
+
+Some[1].or(Some[2])  # => Some[1]
+Some[1].or(None[])   # => Some[1]
+None[].or(Some[2])   # => Some[2]
+None[].or(None[])    # => None
+
+Some[1].or_else { Some[2] }  # => Some[1]
+None[].or_else { Some[2] }   # => Some[2]
+None[].or_else { None[] }    # => None
+
+Some[1].xor(Some[2])  # => None
+Some[1].xor(None[])   # => Some[1]
+None[].xor(Some[2])   # => Some[2]
+None[].xor(None[])    # => None
+```
+
+### String Representation and Formatting
+
+Options provide clear string representations:
+
+```ruby
+require 'data/option'
+
+include Data::Option
+
+Some[42].to_s     # => "Some[42]"
+Some[42].inspect  # => "Some[42]"
+None[].to_s       # => "None"
+None[].inspect    # => "None"
+
+Some[[1, 2, 3]].inspect         # => "Some[[1, 2, 3]]"
+Some[Some["hello"]].inspect     # => "Some[Some[\"hello\"]]"
+
+require 'pp'
+PP.pp(Some[42])             # Some[ 42 ]
+PP.pp(Some[Some[None[]]])   # Some[ Some[ None ] ]
+```
+
+### Comparison and Sorting
+
+`Some` and `None` are comparable and sortable. `None` is considered lower than all `Some` values, and `Some` values are ordered by their contained values:
+
+```ruby
+require 'data/option'
+
+include Data::Option
+
+Some[1] < Some[2]  # => true
+Some[2] > Some[1]  # => true
+Some[1] == Some[1] # => true
+
+Some[1] > None[]   # => true
+None[] < Some[1]   # => true
+
+[Some[3], None[], Some[1], Some[2]].sort  # => [None[], Some[1], Some[2], Some[3]]
+```
+
+### Method Chaining
+
+Chain operations for elegant functional transformations:
+
+```ruby
+require 'data/option'
+
+include Data::Option
+
+Option(42)
+  .map { |it| it * 10 }               # => Some[420]
+  .flat_map { |it| Option(it - 440) } # => Some[-20]
+  .filter(&:positive?)                # => None
+  .map { |it| it * 10 }               # => None
+  .unwrap_or(99)                      # => 99
+```
+
+### Method Overview
+
+`Some` and `None` both respond to a wide range of utility methods that cover common functional programming patterns:
+
+- Checking: `some?`, `none?`, `some_and?`, `none_or?`
+- Unwrapping: `unwrap`, `unwrap_or`, `unwrap_or_else`, `expect`
+- Transforming: `map`, `flat_map`, `filter`, `flatten`, `map_or`, `map_or_else`, `each`
+- Combining: `and`, `and_then`, `or`, `or_else`, `xor`
+- Formatting: `to_s`, `inspect`
+- Comparison: `<=>`, `==`, `<`, `>`, etc.
+
+See Rust's Option [Method overview](https://doc.rust-lang.org/std/option/#method-overview) for background and inspiration for these methods.

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+require 'rubocop/rake_task'
+
+task default: %i[test rubocop]
+
+Rake::TestTask.new do |test|
+  test.pattern = 'test/**/*_test.rb'
+  test.warning = false
+end
+
+RuboCop::RakeTask.new do |task|
+  task.plugins << 'rubocop-minitest'
+end

data/Steepfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+target :lib do
+  signature 'sig'
+  check 'lib'
+  library 'singleton'
+end

data/examples/try_division.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'data/option'
+
+include Data::Option
+
+# An integer division that doesn't `raise ZeroDivisionError`
+def checked_division(dividend, divisor)
+  if divisor.zero?
+    # Failure is represented as the `None` variant
+    None[]
+  else
+    # Result is wrapped in a `Some` variant
+    Some[dividend / divisor]
+  end
+end
+
+# This function handles a division that may not succeed
+def try_division(dividend, divisor)
+  # `Option` values can be pattern matched, just like other enums
+  case checked_division(dividend, divisor)
+  in None
+    puts "#{dividend} / #{divisor} failed!"
+  in Some(quotient)
+    puts "#{dividend} / #{divisor} = #{quotient}"
+  end
+end
+
+try_division(4, 2)
+# >> 4 / 2 = 2
+try_division(1, 0)
+# >> 1 / 0 failed!

data/lib/data/option/ext/kernel.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Kernel
+  private
+
+  def Option(value) = Data::Option.from(value)
+end

data/lib/data/option/none.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+class Data
+  module Option
+    None = Data.define
+    class None
+      class UnwrapError < StandardError
+        def initialize(message = 'cannot unwrap a `None` value') = super
+      end
+
+      include Comparable
+      include Singleton
+
+      def <=>(other) = other.is_a?(Some) ? -1 : 0
+
+      class << self
+        alias [] instance
+      end
+
+      def unwrap = raise UnwrapError
+      def unwrap_or_else = yield
+
+      def unwrap_or(default) = default
+      def expect(message) = raise UnwrapError, message
+
+      def and(_other) = self
+      def and_then = self
+      def or(other) = other.is_a?(Some) ? other : self
+      alias or_else unwrap_or_else
+      alias xor or
+
+      def each = self
+      alias map each
+      alias filter each
+      alias flat_map each
+      alias flatten each
+
+      alias map_or unwrap_or
+      def map_or_else(default) = default.call
+
+      def some? = false
+      def none? = true
+
+      alias some_and? some?
+      alias none_or? none?
+
+      def inspect = 'None'
+      alias to_s inspect
+
+      def pretty_print(pp) = pp.text(inspect)
+    end
+  end
+end

data/lib/data/option/refinement.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class Data
+  module Option
+    module Refinement
+      refine Object do
+        def to_option = Option::Some[self]
+      end
+
+      refine NilClass do
+        def to_option = Option::None[]
+      end
+    end
+  end
+end

data/lib/data/option/some.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+class Data
+  module Option
+    Some = Data.define(:value) do
+      include Comparable
+
+      def <=>(other)
+        return 1 if other.is_a?(None)
+
+        value <=> other.value
+      end
+
+      alias unwrap value
+      alias unwrap_or_else value
+
+      def unwrap_or(_default) = value
+      def expect(_message) = value
+
+      def and(other) = other.is_a?(Some) ? other : None[]
+      def and_then = yield value
+      def or(_other) = self
+      def or_else = self
+      def xor(other) = other.is_a?(Some) ? None[] : self
+
+      def each
+        yield value
+
+        self
+      end
+
+      def map = Some[yield value]
+      def filter = yield(value) ? self : None[]
+      def flat_map(&) = map(&).flatten
+
+      def flatten
+        case value
+        in None | Some
+          value
+        else
+          self
+        end
+      end
+
+      def map_or(_default) = yield value
+      alias map_or_else map_or
+
+      def some? = true
+      def none? = false
+
+      def some_and? = yield value
+      alias none_or? some_and?
+
+      def inspect = "Some[#{value.inspect}]"
+      alias to_s inspect
+
+      def pretty_print(pp)
+        pp.group(1, 'Some[', ']') do
+          pp.breakable('')
+          case value
+          in Some | None
+            value.pretty_print(pp)
+          else
+            pp.pp(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/data/option/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class Data
+  module Option
+    VERSION = '0.1.0'
+  end
+end

data/lib/data/option.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'option/ext/kernel'
+require_relative 'option/none'
+require_relative 'option/refinement'
+require_relative 'option/some'
+require_relative 'option/version'
+
+class Data
+  module Option
+    # Creates an Option from a value.
+    # Returns `None` if the value is `nil`, otherwise returns `Some[value]`.
+    def self.from(value)
+      value.nil? ? None[] : Some[value]
+    end
+  end
+end

data/sig/data/option.rbs

@@ -0,0 +1,81 @@
+type option[T] = Data::Option::Some[T] | Data::Option::None
+
+class Data
+  module Option
+    VERSION: String
+    def self.from: [T] (T?) -> option[T]
+
+    class Some[T]
+      attr_reader value: T
+      def self.[]: [T] (T) -> Some[T]
+      def initialize: (T) -> void
+      def <=>: (None) -> 1
+              | (Some[untyped]) -> (1 | 0 | -1 | nil)
+      def unwrap: -> T
+      def unwrap_or: (untyped) -> T
+      def unwrap_or_else: -> T
+      def expect: (untyped) -> T
+      def and: (untyped) -> option[untyped]
+      def and_then: { (T) -> option[untyped] } -> option[untyped]
+      def or: (untyped) -> Some[T]
+      def or_else: -> Some[T]
+      def xor: (untyped) -> option[untyped]
+      def each: { (T) -> void } -> Some[T]
+      def map: { (T) -> untyped } -> Some[untyped]
+      def filter: { (T) -> boolish } -> option[T]
+      def flat_map: { (T) -> untyped } -> untyped
+      def flatten: -> untyped
+      def map_or: (untyped) { (T) -> untyped } -> untyped
+      def map_or_else: (untyped) { (T) -> untyped } -> untyped
+      def some?: -> true
+      def none?: -> false
+      def some_and?: { (T) -> boolish } -> boolish
+      def none_or?: { (T) -> boolish } -> boolish
+      def to_s: -> String
+      def inspect: -> String
+      def pretty_print: (PP) -> void
+    end
+
+    class None
+      class UnwrapError < StandardError
+        def initialize: (?String) -> void
+      end
+      
+      def self.[]: -> None
+      def initialize: () -> void
+      def <=>: (Some[untyped]) -> -1
+              | (None) -> 0
+      def unwrap: -> untyped
+      def unwrap_or_else: { () -> untyped } -> untyped
+      def unwrap_or: (untyped) -> untyped
+      def expect: (untyped) -> untyped
+      def and: (untyped) -> None
+      def and_then: -> None
+      def or: (untyped) -> untyped
+      def or_else: { () -> untyped } -> untyped
+      def xor: (untyped) -> untyped
+      def each: { (untyped) -> void } -> None
+      def map: { (untyped) -> untyped } -> None
+      def filter: { (untyped) -> untyped } -> None
+      def flat_map: { (untyped) -> untyped } -> None
+      def flatten: -> None
+      def map_or: (untyped) { (untyped) -> untyped } -> untyped
+      def map_or_else: (untyped) -> untyped
+      def some?: -> false
+      def none?: -> true
+      def some_and?: { (untyped) -> untyped } -> false
+      def none_or?: { (untyped) -> untyped } -> true
+      def to_s: -> String
+      def inspect: -> String
+      def pretty_print: (PP) -> void
+    end
+
+    module Refinement
+      def to_option: () -> option[self]
+    end
+  end
+end
+
+module Kernel
+  def Option: (untyped) -> option[untyped]
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: data-option
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shannon Skipper
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Some and None Option classes with Rust-like semantics
+email:
+- shannonskipper@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- LICENSE.txt
+- README.md
+- Rakefile
+- Steepfile
+- examples/try_division.rb
+- lib/data/option.rb
+- lib/data/option/ext/kernel.rb
+- lib/data/option/none.rb
+- lib/data/option/refinement.rb
+- lib/data/option/some.rb
+- lib/data/option/version.rb
+- sig/data/option.rbs
+homepage: https://github.com/havenwood/data-option
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/havenwood/data-option
+  source_code_uri: https://github.com/havenwood/data-option
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.0.dev
+specification_version: 4
+summary: Option classes for Some and None
+test_files: []