standard-procedure-plumbing 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00f89cef3ca3db2daf437446af1788755906434de2ec2d4e6e81130b26190f84
-  data.tar.gz: 44d27c6f52de7bbc24c488f741035d0a9fe4341036c423e51b5031896ca9f50a
+  metadata.gz: 6074870313ece34eb4b9565602db4de70bb5b7e14e8a9051d85bb46b6fc64bf5
+  data.tar.gz: a81292b0ad9e87dfcce61d531e891c1b4ed25ccda3331ceb731c082c6e9c7c16
 SHA512:
-  metadata.gz: 6785c35e5596df5718a8ce458ced0713abbe3d18516a90b6353c806da8f867d3bf4d48d70b8b31b15b7c23a491fa2c855c091250aa96bdf97595f813b53e8e18
-  data.tar.gz: 22169d08af47f789dd5a950635ad46598c6a77f402a2221ed719f369df00b065185b402f14ba2dd2dd82b54cac8774d67d1adc2c07524307a644be11707d7956
+  metadata.gz: 45827e921f7bc272e0688a6477d405a81e8c9ea64405078782fbf5aa45658066bf7f9c5503692f4f6eadfdbb08d21221eb4e0b0731654e4808e0f7ec1111f9bb
+  data.tar.gz: 1ba319545accf7051393845b1883d5eb69aeacba182c86f26ca6e95e7761711e922904d2ec5427872e8dcd6ccdf5fba25737fe5c20a887cc06ba23ab2184c81a

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## [0.2.2] - 2024-08-25
+
+ - Added Plumbing::RubberDuck
+
 ## [0.2.1] - 2024-08-25
 
  - Split the Pipe implementation between the Pipe and EventDispatcher

data/README.md

@@ -58,6 +58,7 @@ BuildSequence.new.call ["extra element"]
 # => Plumbing::PostconditionError("must_have_three_elements")
 ```
 
+
 ## Plumbing::Pipe - a composable observer
 
 [Observers](https://ruby-doc.org/3.3.0/stdlibs/observer/Observable.html) in Ruby are a pattern where objects (observers) register their interest in another object (the observable).  This pattern is common throughout programming languages (event listeners in Javascript, the dependency protocol in [Smalltalk](https://en.wikipedia.org/wiki/Smalltalk)).
@@ -180,6 +181,37 @@ end
 ```
 
 
+## Plumbing::RubberDuck - duck types and type-casts
+
+Define an [interface or protocol](https://en.wikipedia.org/wiki/Interface_(object-oriented_programming) specifying which messages you expect to be able to send.  Then cast an object into that type, which first tests that the object can respond to those messages and limits you to sending those messages and no others.  
+
+
+### Usage 
+
+Define your interface (Person in this example), then cast your objects (instances of PersonData and CarData).  
+
+```ruby
+require "plumbing"
+
+Person = Plumbing::RubberDuck.define :first_name, :last_name, :email 
+
+PersonData = Struct.new(:first_name, :last_name, :email, :favourite_food)
+CarData = Struct.new(:make, :model, :colour)
+
+@porsche_911 = CarData.new "Porsche", "911", "black"
+@person = @porsche_911.as Person
+# => Raises a TypeError 
+
+@alice = PersonData.new "Alice", "Aardvark", "alice@example.com", "Ice cream"
+@person = @alice.as Person
+@person.first_name
+# => "Alice"
+@person.email 
+# => "alice@example.com"
+@person.favourite_food
+# => NoMethodError - even though :favourite_food is a field in PersonData, it is not included in the definition of Person so cannot be accessed through the RubberDuck type
+```
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -194,7 +226,6 @@ Then:
 require 'plumbing'
 ```
 
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/checksums/standard-procedure-plumbing-0.2.2.gem.sha512

@@ -0,0 +1 @@
+2309f738a6739650f259c456af69796e59c1de214579a8a274d56b7ccc8176e9e59cb0e63d744bd5a6ed40e93f4c57a368c3de2bc525163e90da9467a58c6387

data/lib/plumbing/error.rb

@@ -10,10 +10,4 @@ module Plumbing
 
   # Error raised because an invalid [Event] object was pushed into the pipe
   class InvalidEvent < Error; end
-
-  # Error raised because an invalid observer was registered
-  class InvalidObserver < Error; end
-
-  # Error raised because a Pipe was connected to a non-Pipe
-  class InvalidSource < Plumbing::Error; end
 end

data/lib/plumbing/event_dispatcher/fiber.rb

@@ -47,7 +47,7 @@ module Plumbing
       end
 
       def dispatch_event event, task
-        @observers.collect do |observer|
+        @observers.each do |observer|
           task.async do
             observer.call event
           rescue => ex

data/lib/plumbing/event_dispatcher.rb

@@ -1,13 +1,12 @@
 module Plumbing
   class EventDispatcher
     def initialize observers: []
-      @observers = observers
+      @observers = observers.as(Collection)
     end
 
     def add_observer observer = nil, &block
       observer ||= block.to_proc
-      raise Plumbing::InvalidObserver.new "observer_does_not_respond_to_call" unless observer.respond_to? :call
-      @observers << observer
+      @observers << observer.as(Callable).target
       observer
     end
 
@@ -20,7 +19,7 @@ module Plumbing
     end
 
     def dispatch event
-      @observers.collect do |observer|
+      @observers.each do |observer|
         observer.call event
       rescue => ex
         puts ex

data/lib/plumbing/filter.rb

@@ -6,9 +6,8 @@ module Plumbing
     # @param &accepts [Block] a block that returns a boolean value - true to accept the event, false to reject it
     def initialize source:, dispatcher: nil, &accepts
       super(dispatcher: dispatcher)
-      raise InvalidSource.new "#{source} must be a Plumbing::Pipe descendant" unless source.is_a? Plumbing::Pipe
-      @accepts = accepts
-      source.add_observer do |event|
+      @accepts = accepts.as(Callable)
+      source.as(Observable).add_observer do |event|
         filter_and_republish event
       end
     end

data/lib/plumbing/junction.rb

@@ -11,8 +11,7 @@ module Plumbing
     private
 
     def add source
-      raise InvalidSource.new "#{source} must be a Plumbing::Pipe descendant" unless source.is_a? Plumbing::Pipe
-      source.add_observer do |event|
+      source.as(Observable).add_observer do |event|
         dispatch event
       end
       source

data/lib/plumbing/pipe.rb

@@ -5,7 +5,7 @@ module Plumbing
 
     # Subclasses should call `super()` to ensure the pipe is initialised corrected
     def initialize dispatcher: nil
-      @dispatcher = dispatcher || EventDispatcher.new
+      @dispatcher = dispatcher.nil? ? EventDispatcher.new : dispatcher.as(DispatchesEvents)
     end
 
     # Push an event into the pipe

data/lib/plumbing/pipeline/contracts.rb

@@ -25,19 +25,19 @@ module Plumbing
 
       def validate_contract_for input
         return true if @validation_contract.nil?
-        result = const_get(@validation_contract).new.call(input)
+        result = const_get(@validation_contract).new.as(Callable).call(input)
         raise PreConditionError, result.errors.to_h.to_yaml unless result.success?
         input
       end
 
       def validate_preconditions_for input
-        failed_preconditions = pre_conditions.select { |name, validator| !validator.call(input) }
+        failed_preconditions = pre_conditions.select { |name, validator| !validator.as(Callable).call(input) }
         raise PreConditionError, failed_preconditions.keys.join(", ") if failed_preconditions.any?
         input
       end
 
       def validate_postconditions_for output
-        failed_postconditions = post_conditions.select { |name, validator| !validator.call(output) }
+        failed_postconditions = post_conditions.select { |name, validator| !validator.as(Callable).call(output) }
         raise PostConditionError, failed_postconditions.keys.join(", ") if failed_postconditions.any?
         output
       end

data/lib/plumbing/pipeline/operations.rb

@@ -18,7 +18,7 @@ module Plumbing
         validate_preconditions_for input
         result = input
         operations.each do |operation|
-          result = operation.call(result, instance)
+          result = operation.as(Callable).call(result, instance)
         end
         validate_postconditions_for result
         result
@@ -37,7 +37,7 @@ module Plumbing
 
       def perform_external method, class_or_class_name
         external_class = class_or_class_name.is_a?(String) ? const_get(class_or_class_name) : class_or_class_name
-        implementation = ->(input, instance) { external_class.new.call(input) }
+        implementation = ->(input, instance) { external_class.new.as(Callable).call(input) }
         operations << implementation
       end
     end

data/lib/plumbing/rubber_duck/object.rb

@@ -0,0 +1,9 @@
+module Plumbing
+  class RubberDuck
+    ::Object.class_eval do
+      def as duck_type
+        duck_type.proxy_for self
+      end
+    end
+  end
+end

data/lib/plumbing/rubber_duck/proxy.rb

@@ -0,0 +1,16 @@
+module Plumbing
+  class RubberDuck
+    class Proxy
+      attr_reader :target
+
+      def initialize target, duck_type
+        @target = target
+        @duck_type = duck_type
+      end
+
+      def as duck_type
+        (duck_type == @duck_type) ? self : duck_type.proxy_for(target)
+      end
+    end
+  end
+end

data/lib/plumbing/rubber_duck.rb

@@ -0,0 +1,50 @@
+module Plumbing
+  # A type-checker for duck-types
+  class RubberDuck
+    require_relative "rubber_duck/object"
+    require_relative "rubber_duck/proxy"
+
+    def initialize *methods
+      @methods = methods.map(&:to_sym)
+      @proxy_classes = {}
+    end
+
+    def verify object
+      missing_methods = @methods.reject { |method| object.respond_to? method }
+      raise TypeError, "Expected object to respond to #{missing_methods.join(", ")}" unless missing_methods.empty?
+      object
+    end
+
+    def proxy_for object
+      is_a_proxy?(object) || build_proxy_for(object)
+    end
+
+    def self.define *methods
+      new(*methods)
+    end
+
+    private
+
+    def is_a_proxy? object
+      @proxy_classes.value?(object.class) ? object : nil
+    end
+
+    def build_proxy_for object
+      proxy_class_for(object).new(verify(object), self)
+    end
+
+    def proxy_class_for object
+      @proxy_classes[object.class] ||= define_proxy_class_for(object.class)
+    end
+
+    def define_proxy_class_for klass
+      Class.new(Plumbing::RubberDuck::Proxy).tap do |proxy_class|
+        @methods.each do |method|
+          proxy_class.define_method method do |*args, &block|
+            @target.send method, *args, &block
+          end
+        end
+      end
+    end
+  end
+end

data/lib/plumbing/types.rb

@@ -0,0 +1,6 @@
+module Plumbing
+  Callable = RubberDuck.define :call
+  Observable = RubberDuck.define :add_observer, :remove_observer, :is_observer?
+  DispatchesEvents = RubberDuck.define :add_observer, :remove_observer, :is_observer?, :shutdown, :dispatch
+  Collection = RubberDuck.define :each, :<<, :delete, :include?
+end

data/lib/plumbing/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Plumbing
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

data/lib/plumbing.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-require_relative "plumbing/version"
-
-require_relative "plumbing/error"
-require_relative "plumbing/event"
-require_relative "plumbing/pipe"
-require_relative "plumbing/filter"
-require_relative "plumbing/junction"
-require_relative "plumbing/pipeline"
-
 module Plumbing
+  require_relative "plumbing/rubber_duck"
+  require_relative "plumbing/types"
+  require_relative "plumbing/error"
+  require_relative "plumbing/event"
+  require_relative "plumbing/pipe"
+  require_relative "plumbing/filter"
+  require_relative "plumbing/junction"
+  require_relative "plumbing/pipeline"
+  require_relative "plumbing/version"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard-procedure-plumbing
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Rahoul Baruah
@@ -31,6 +31,7 @@ files:
 - checksums/standard-procedure-plumbing-0.1.2.gem.sha512
 - checksums/standard-procedure-plumbing-0.2.0.gem.sha512
 - checksums/standard-procedure-plumbing-0.2.1.gem.sha512
+- checksums/standard-procedure-plumbing-0.2.2.gem.sha512
 - lib/plumbing.rb
 - lib/plumbing/error.rb
 - lib/plumbing/event.rb
@@ -42,6 +43,10 @@ files:
 - lib/plumbing/pipeline.rb
 - lib/plumbing/pipeline/contracts.rb
 - lib/plumbing/pipeline/operations.rb
+- lib/plumbing/rubber_duck.rb
+- lib/plumbing/rubber_duck/object.rb
+- lib/plumbing/rubber_duck/proxy.rb
+- lib/plumbing/types.rb
 - lib/plumbing/version.rb
 - sig/plumbing.rbs
 homepage: https://github.com/standard-procedure/plumbing