safe_and_sound 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8ea298c0193785c3c404e220a34f34bd30f00ced83729c1dc576010e015b7165
+  data.tar.gz: 38455c727045bccff6dfa5cb17795960fcd51356f942aed7c6b982de21267482
+SHA512:
+  metadata.gz: 395c899676cbd7656ace2655062f68b191798cec6ff9a68bdee5bf7b889b9cfd8ace657f74c1aaefc2d7a214fc1f8c4d6463f531064641e9febc31233a8b6b71
+  data.tar.gz: 749967441723e4dea3d01d43bb41cae4d6661a8826eb511b5431181098ad76a372c9634307a47069c2800d476f868202b3d823a2bdb5e74a6fa30b6ffbe30d2f

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.0.1 (04-Apr-22)
+
+* Initial release

data/README.md

@@ -0,0 +1,62 @@
+![Unit tests](https://github.com/axelerator/safe_and_sound/actions/workflows/run-tests.yml/badge.svg)
+
+# Safe and Sound: Sum Data Types and utilities for Ruby
+
+This library gives you and alternative syntax to declare new types/classes.
+It's inspired by the concise syntax to declare new types in [Elm](https://guide.elm-lang.org/types/custom_types.html) or [Haskell](https://www.schoolofhaskell.com/user/Gabriel439/sum-types)
+These types share some properties with types referred to as _algebaric data types_, _sum types_ or _union types_.
+
+We can model similar relationships more verbosely in plain Ruby with classes and subclasses.
+This library provides some syntactic shortcuts to create these hierarchy.
+
+```ruby
+Vehicle = SafeAndSound.new(
+    Car: { horsepower: Integer },
+    Bike: { gears: Integer}
+  )
+```
+
+This will create an abstract base class `Vehicle`.
+Instances can only be created for the __concrete__ subclasses `Car` or `Bike`.
+The class names act as "constructor" functions and values created that way are immutable.
+
+```ruby
+car = Vehicle.car(horsepower: 100)
+puts car.horsepower # 100
+
+bike = Vehicle.bike(gears: 'twentyone')
+# SafeAndSound::WrgonConstructorArgType (gears must be of type Integer but was String)
+```
+
+`nil` is **not** a valid constructor argument. Optional values can be modeled with the [`Maybe` type](examples/maybe.rb) that is also provided with the library.
+
+To add polymorphic behavior we can write functions __without__ having to touch the new types themselves.
+
+By including the `SafeAndSound::Functions` module we get access to the `chase` function.
+It immitates the `case` statement but uses the knowledge about our types to make it more safe.
+
+```ruby
+include SafeAndSound::Functions
+
+def to_human(vehicle)
+  chase vehicle do
+    Vehicle::Car,  -> { "I'm a car with #{horsepower} horsepower" }
+    Vehicle::Bike, -> { "I'm a bike with #{gears} gears" }
+  end
+end
+```
+
+This offers a stricter version of the case statement.
+Specifically it makes sure that all variants are handled (unless an `otherwise` block is given).
+This check will still be only performed at runtime, but as long as there is at least one test executing this
+`chase` expression we'll get an early, precise exception telling us what's missing.
+
+If you want a more detailed explanation why working with such objects can be appealing I recommend you watch the
+[Functional Core, Imperative Shell](https://www.destroyallsoftware.com/screencasts/catalog/functional-core-imperative-shell)
+episode of the _Destroy all software_ screencast.
+
+I'm not trying to change how Ruby code is written. This is merely an experiment how far the sum type concept can be taken in terms
+of making a syntax for it look like the syntax in languages where this concept is more central.
+
+
+

data/lib/safe_and_sound/functions.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module SafeAndSound
+  ##
+  # Include this module to get access to functions that
+  # work on the algebraic data types.
+  module Functions
+    ##
+    # This is an interpretation of Ruby's case statement for
+    # ADTs.
+    def chase(value, &block)
+      Chase.new(value).run(block)
+    end
+  end
+
+  class MatchedChaseValueNotAVariant < StandardError; end
+  class MissingChaseBranch < StandardError; end
+  class DuplicateChaseBranch < StandardError; end
+  class ChaseValueNotAVariant < StandardError; end
+
+  ##
+  # Instance represent one application of a 'chase'
+  # statement.
+  class Chase
+    NO_MATCH = Object.new
+    NO_FALLBACK = Object.new
+
+    def initialize(object)
+      unless object.respond_to?(:variant_type?)
+        raise ChaseValueNotAVariant,
+              "Matched value in chase expression must be a variant but is a #{object.class.name}"
+      end
+
+      @result = NO_MATCH
+      @object = object
+      @to_match = object.class.superclass.variants.dup
+      @otherwise = NO_FALLBACK
+    end
+
+    def run(block)
+      instance_eval(&block)
+      unless @to_match.empty? || @otherwise != NO_FALLBACK
+        raise MissingChaseBranch,
+              "Missing branches for variants: #{@to_match.map(&:variant_name).join(',')}"
+      end
+      return @otherwise if @result == NO_MATCH
+
+      @result
+    end
+
+    def wenn(variant, lmda)
+      unless variant.is_a?(Class) && variant.superclass == @object.class.superclass
+        raise MatchedChaseValueNotAVariant,
+              "The value matched against must be a variant of #{@object.class.superclass.name} "\
+              "but is a #{variant.class}"
+      end
+      unless @to_match.delete(variant)
+        raise DuplicateChaseBranch,
+              "There are multiple branches for variant: #{variant.variant_name}"
+      end
+      return unless @result == NO_MATCH
+
+      @result = @object.instance_exec(&lmda) if @object.is_a? variant
+    end
+
+    def otherwise(value)
+      @otherwise = value.call
+    end
+  end
+end

data/lib/safe_and_sound/maybe.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module SafeAndSound
+  Maybe = SafeAndSound.new(
+    Just: { value: Object },
+    Nothing: {}
+  )
+
+  module MaybeMethods
+    def with_default(default)
+      chase self do
+        wenn Maybe::Just, -> { value }
+        wenn Maybe::Nothing, -> { default }
+      end
+    end
+  end
+
+  module MaybeClassMethods
+    include SafeAndSound::Functions
+    def values(maybes)
+      maybes.inject([]) do |sum, maybe|
+        chase maybe do
+          wenn Maybe::Just, -> { sum.push(value) }
+          wenn Maybe::Nothing, -> { sum }
+        end
+      end
+    end
+  end
+  Maybe.include(MaybeMethods)
+  Maybe.extend(MaybeClassMethods)
+end

data/lib/safe_and_sound/result.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SafeAndSound
+  Result = SafeAndSound.new(
+    Ok: { value: Object },
+    Err: { error: Object }
+  )
+  ##
+  # Module with methods we want to add to our Result type
+  module ResultMethods
+    def and_then(&block)
+      chase self do
+        wenn Result::Ok, ->  { block.call(value) }
+        wenn Result::Err, -> { self }
+      end
+    end
+  end
+  Result.include ResultMethods
+end

data/lib/safe_and_sound/type.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module SafeAndSound
+  class BaseTypeCannotBeInstantiated < StandardError; end
+
+  ##
+  # base class for the newly defined types
+  class Type
+    def initialize
+      raise BaseTypeCannotBeInstantiated, 'You cannot create instances of this type directly but only of its variants'
+    end
+
+    class << self
+      attr_accessor :variants
+    end
+  end
+end

data/lib/safe_and_sound/variant.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module SafeAndSound
+  class MissingConstructorArg < StandardError; end
+  class UnknownConstructorArg < StandardError; end
+  class WrgonConstructorArgType < StandardError; end
+
+  ##
+  # base class for a variant of the newly defined types
+  module Variant
+    ##
+    # Mixin used in Variant types to initialize fields from
+    # constructor arguments.
+    module Initializer
+      def initialize_fields(**args)
+        missing_fields = self.class.fields.keys
+        args.each do |field_name, value|
+          initialize_field(field_name, value)
+          missing_fields.delete(field_name)
+        end
+
+        return if missing_fields.empty?
+
+        raise MissingConstructorArg, "Not all constructor arguments were supplied: #{missing_fields}"
+      end
+
+      def to_s
+        "<#{self.class.superclass.name}:#{self.class.variant_name} ..."
+      end
+
+      def variant_type?
+        true
+      end
+
+      private
+
+      def initialize_field(field_name, value)
+        field_type = self.class.fields[field_name]
+        if field_type.nil?
+          raise UnknownConstructorArg,
+                "#{self.class.name} does not have a constructor argument #{field_name}"
+        end
+
+        unless value.is_a?(field_type)
+          raise WrgonConstructorArgType,
+                "#{field_name} must be of type #{field_type} but was #{value.class.name}"
+        end
+        instance_variable_set("@#{field_name}", value)
+      end
+    end
+
+    def self.build(variant_name, fields, parent_type)
+      new_variant = create_variant_type(parent_type)
+      new_variant.fields = fields
+      new_variant.variant_name = variant_name
+      fields.each { |field, _| new_variant.attr_reader field }
+      parent_type.const_set(variant_name.to_s, new_variant)
+      parent_type.define_singleton_method(variant_name) do |**args|
+        new_variant.new(**args)
+      end
+      new_variant
+    end
+
+    def self.create_variant_type(parent_type)
+      Class.new(parent_type) do
+        include(Initializer)
+        include(Functions)
+        class << self
+          attr_accessor :fields, :variant_name
+        end
+
+        def initialize(**args)
+          initialize_fields(**args)
+        end
+      end
+    end
+  end
+end

data/lib/safe_and_sound/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SafeAndSound
+  VERSION = '0.1.0'
+end

data/lib/safe_and_sound.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'safe_and_sound/functions'
+require 'safe_and_sound/type'
+require 'safe_and_sound/variant'
+require 'safe_and_sound/version'
+
+##
+# Namespace for the safe_and_sound classes
+module SafeAndSound
+  def self.new(**variants)
+    new_type = Class.new(Type)
+
+    new_type.variants =
+      variants.map do |variant_name, fields|
+        Variant.build(variant_name, fields, new_type)
+      end
+    new_type
+  end
+end
+
+require 'safe_and_sound/result'
+require 'safe_and_sound/maybe'

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: safe_and_sound
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Axel Tetzlaff
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-04-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 13.0.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 13.0.6
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.15'
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.26'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.26'
+description: A compact DSL to let you declare sum data types and define safe functions
+  on them.
+email: axel.tetzlaff@gmx.de
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- CHANGELOG.md
+- README.md
+- lib/safe_and_sound.rb
+- lib/safe_and_sound/functions.rb
+- lib/safe_and_sound/maybe.rb
+- lib/safe_and_sound/result.rb
+- lib/safe_and_sound/type.rb
+- lib/safe_and_sound/variant.rb
+- lib/safe_and_sound/version.rb
+homepage: https://github.com/axelerator/safe_and_sound
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: Sum Data Types
+test_files: []