plumb 0.0.18 → 0.2.0.beta.2

data/lib/plumb/policy.rb

@@ -14,6 +14,9 @@ module Plumb
     # @param policy_name [Symbol]
     # @param arg [Object, nil] the argument to the policy, if any.
     # @param step [Step] the step composition wrapped by this policy.
+    # @see Plumb::NodeMapper
+    def with_children(children) = self.class.new(policy_name, arg, children.first)
+
     def initialize(policy_name, arg, step)
       @policy_name = policy_name
       @arg = arg
@@ -22,15 +25,25 @@ module Plumb
       freeze
     end
 
+    # Policy equality includes the wrapped step; otherwise same-named policies on
+    # disjoint types would compare equal and one could be reduced away.
+    # @param other [Object]
+    # @return [Boolean]
     def ==(other)
-      other.is_a?(self.class) &&
+      other.instance_of?(self.class) &&
         policy_name == other.policy_name &&
-        arg == other.arg
+        arg == other.arg &&
+        children == other.children
     end
 
+    # A Policy is a transparent wrapper: it delegates type-flow to the wrapped
+    # step.
+    def input_type = @step.input_type
+    def output_type = @step.output_type
+
     # The standard Step interface.
-    # @param result [Result::Valid]
-    # @return [Result::Valid, Result::Invalid]
+    # @param result [Result]
+    # @return [Result]
     def call(result) = @step.call(result)
 
     private def _inspect = @step.inspect

data/lib/plumb/range_class.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'plumb/composable'
+
+module Plumb
+  class RangeClass
+    include Composable
+
+    attr_reader :children
+
+    def initialize(member_type = Types::Any)
+      @member_type = Composable.wrap(member_type)
+      @children = [@member_type].freeze
+      freeze
+    end
+
+    def of(member_type)
+      self.class.new(member_type)
+    end
+
+    alias [] of
+
+    # #call only validates the Range's endpoints against the member type — it
+    # never coerces or rebuilds the Range — so a Range type always returns its
+    # input unchanged, regardless of member. This lets `#|` absorb a narrower
+    # branch (`Range[Integer] | Range[1..10]` -> `Range[Integer]`) and `#>>`
+    # drop a redundant re-check.
+    def value_preserving? = true
+
+    def call(result)
+      return result.invalid!(errors: 'must be a Range') unless result.value.is_a?(::Range)
+
+      range = result.value
+      [range.begin, range.end].compact.each do |endpoint|
+        r = @member_type.resolve(endpoint)
+        return result.invalid!(errors: r.errors) unless r.valid?
+      end
+
+      result
+    end
+
+    private
+
+    def _inspect = %(Range[#{@member_type}])
+  end
+end

data/lib/plumb/relation.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Plumb
+  # Internal three-valued result for propositions the type algebra attempts to
+  # prove. Unknown is distinct from false so callers cannot turn missing
+  # knowledge into an unsafe rewrite.
+  class Relation
+    class << self
+      # Converts a known predicate result to a proof.
+      # @param value [Object]
+      # @return [Relation]
+      def from(value) = value ? PROVEN : DISPROVEN
+
+      # Combines proofs for a logical conjunction.
+      # @param relations [Enumerable<Relation>]
+      # @return [Relation]
+      def all(relations)
+        unknown = false
+        relations.each do |relation|
+          return DISPROVEN if relation.disproven?
+
+          unknown ||= relation.unknown?
+        end
+        unknown ? UNKNOWN : PROVEN
+      end
+
+      # Combines proofs for a logical disjunction.
+      # @param relations [Enumerable<Relation>]
+      # @return [Relation]
+      def any(relations)
+        unknown = false
+        relations.each do |relation|
+          return PROVEN if relation.proven?
+
+          unknown ||= relation.unknown?
+        end
+        unknown ? UNKNOWN : DISPROVEN
+      end
+
+      private :new
+    end
+
+    # @return [Boolean]
+    def proven? = equal?(PROVEN)
+
+    # @return [Boolean]
+    def disproven? = equal?(DISPROVEN)
+
+    # @return [Boolean]
+    def unknown? = equal?(UNKNOWN)
+
+    PROVEN = new.freeze
+    DISPROVEN = new.freeze
+    UNKNOWN = new.freeze
+  end
+  private_constant :Relation
+end

data/lib/plumb/result.rb

@@ -1,14 +1,38 @@
 # frozen_string_literal: true
 
 module Plumb
+  # The value + validity + errors triple that flows through a composition.
+  #
+  # There are two ways to derive one result from another:
+  #
+  #   - #valid / #invalid ALLOCATE a fresh Result and leave the receiver
+  #     untouched. This is the safe, functional form: use it in custom types, and
+  #     anywhere a result may outlive the call or be captured (Streams close over
+  #     it lazily; concurrent Arrays hand results between threads). This is the
+  #     public API for user-defined steps.
+  #
+  #   - #valid! / #invalid! FLIP THE RECEIVER in place and return it (no
+  #     allocation). Plumb's own built-in steps use these on the hot path to
+  #     avoid a Result per node — but only where the input cursor is theirs to
+  #     mutate: never on a shared/constant Result, never when the result escapes
+  #     into a closure or another thread. The one fork point (Or) snapshots the
+  #     value and #resets before retrying its second branch.
+  #
+  # So built-ins stay allocation-lean while user code (and the concurrency- and
+  # laziness-sensitive built-ins) keep the footgun-free copying semantics, at the
+  # cost of a few extra allocations there.
+  #
+  # Valid and Invalid were once separate subclasses; collapsing them into one
+  # class with a boolean is what makes the in-place valid<->invalid flip possible
+  # (Ruby can't change an object's class).
   class Result
     class << self
-      def valid(value)
-        Valid.new(value)
+      def valid(value = nil)
+        new(value, valid: true)
       end
 
       def invalid(value = nil, errors: nil)
-        Invalid.new(value, errors:)
+        new(value, valid: false, errors:)
       end
 
       def wrap(value)
@@ -20,24 +44,20 @@ module Plumb
 
     attr_reader :value, :errors
 
-    def initialize(value, errors: nil)
+    def initialize(value, valid: true, errors: nil)
       @value = value
+      @valid = valid
       @errors = errors
     end
 
-    def valid? = true
-    def invalid? = false
+    def valid? = @valid
+    def invalid? = !@valid
 
     def inspect
-      %(<#{self.class}##{object_id} value:#{value.inspect} errors:#{errors.inspect}>)
-    end
-
-    def reset(val)
-      @value = val
-      @errors = nil
-      self
+      %(<#{self.class}##{object_id} valid:#{@valid} value:#{value.inspect} errors:#{errors.inspect}>)
     end
 
+    # Allocating, copy-returning form. Safe everywhere: the receiver is untouched.
     def valid(val = value)
       Result.valid(val)
     end
@@ -46,19 +66,31 @@ module Plumb
       Result.invalid(val, errors:)
     end
 
-    class Valid < self
-      def map(callable)
-        callable.call(self)
-      end
+    # In-place form: flip THIS result and return self. No allocation. Only for
+    # code that owns the cursor (see the class docstring).
+    def valid!(val = value)
+      @value = val
+      @valid = true
+      @errors = nil
+      self
     end
 
-    class Invalid < self
-      def valid? = false
-      def invalid? = true
+    def invalid!(val = value, errors: nil)
+      @value = val
+      @valid = false
+      @errors = errors
+      self
+    end
 
-      def map(_)
-        self
-      end
+    # Reset the cursor to a fresh VALID state carrying `val`, in place. The
+    # mutating scratch-reuse primitive behind the HashClass/ArrayClass element
+    # loops (same as #valid!(val)).
+    def reset(val)
+      valid!(val)
+    end
+
+    def map(callable)
+      @valid ? callable.call(self) : self
     end
   end
 end

data/lib/plumb/semantic_matcher.rb

@@ -0,0 +1,393 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Plumb
+  # Internal semantic form of Ruby `#===` matchers. Raw matchers are normalized
+  # once at a Constraint boundary; nodes then collaborate polymorphically.
+  module SemanticMatcher
+    class Merge
+      attr_reader :node
+
+      class << self
+        def merged(node) = new(:merged, node)
+
+        private :new
+      end
+
+      def initialize(state, node = nil)
+        @state = state
+        @node = node
+        freeze
+      end
+
+      def merged? = @state == :merged
+      def empty? = equal?(EMPTY)
+      def unknown? = equal?(UNKNOWN)
+
+      EMPTY = new(:empty)
+      UNKNOWN = new(:unknown)
+    end
+
+    class Node
+      attr_reader :raw
+
+      def initialize(raw)
+        @raw = raw
+        freeze
+      end
+
+      def kind = :opaque
+      def singleton? = false
+      def nominal? = false
+      def matcher_domain = []
+      def value_domain = raw.class
+      def error_message = "Must match #{raw.inspect}"
+      def matches_value(_candidate) = Relation::UNKNOWN
+
+      def equivalent?(other)
+        other.instance_of?(self.class) && raw == other.raw
+      end
+
+      def subset_of(other)
+        return Relation::PROVEN if equivalent?(other)
+
+        other.subset_from_opaque(self)
+      end
+
+      def subset_from_opaque(_other) = Relation::UNKNOWN
+      def subset_from_nominal(_other) = Relation::UNKNOWN
+      def subset_from_literal(_other) = Relation::UNKNOWN
+      def subset_from_text_literal(other) = subset_from_literal(other)
+      def subset_from_numeric_literal(other) = subset_from_literal(other)
+      def subset_from_finite_set(_other) = Relation::UNKNOWN
+      def subset_from_range(_other) = Relation::UNKNOWN
+      def subset_from_pattern(_other) = Relation::UNKNOWN
+
+      def overlap(other)
+        return Relation::PROVEN if equivalent?(other)
+
+        other.overlap_with_opaque(self)
+      end
+
+      def overlap_with_opaque(_other) = Relation::UNKNOWN
+      def overlap_with_nominal(_other) = Relation::UNKNOWN
+      def overlap_with_literal(_other) = Relation::UNKNOWN
+      def overlap_with_text_literal(other) = overlap_with_literal(other)
+      def overlap_with_numeric_literal(other) = overlap_with_literal(other)
+      def overlap_with_finite_set(_other) = Relation::UNKNOWN
+      def overlap_with_range(_other) = Relation::UNKNOWN
+      def overlap_with_pattern(_other) = Relation::UNKNOWN
+
+      def intersect(_other) = Merge::UNKNOWN
+      def intersect_with_finite_set(_other) = Merge::UNKNOWN
+      def intersect_with_range(_other) = Merge::UNKNOWN
+    end
+
+    class Opaque < Node
+    end
+
+    class CollectionMatcher < Opaque
+      def kind = :collection_matcher
+      def error_message = "Must be equal to #{raw}"
+    end
+
+    class Literal < Node
+      def kind = :literal
+      def singleton? = true
+      def matcher_domain = [value_domain]
+      def matches_value(candidate) = Relation.from(raw === candidate)
+      def error_message = "Must be equal to #{raw}"
+
+      def subset_of(other)
+        return Relation::PROVEN if equivalent?(other)
+
+        other.subset_from_literal(self)
+      end
+
+      def subset_from_literal(_other) = Relation::DISPROVEN
+
+      def overlap(other)
+        return Relation::PROVEN if equivalent?(other)
+
+        other.overlap_with_literal(self)
+      end
+
+      def overlap_with_literal(_other) = Relation::DISPROVEN
+      def overlap_with_nominal(other) = other.overlap_with_literal(self)
+      def overlap_with_range(other) = other.overlap_with_literal(self)
+      def overlap_with_pattern(other) = other.overlap_with_literal(self)
+    end
+
+    class TextLiteral < Literal
+      def kind = :text_literal
+
+      def subset_of(other)
+        return Relation::PROVEN if equivalent?(other)
+
+        other.subset_from_text_literal(self)
+      end
+
+      def overlap(other)
+        return Relation::PROVEN if equivalent?(other)
+
+        other.overlap_with_text_literal(self)
+      end
+    end
+
+    class NumericLiteral < Literal
+      def kind = :numeric_literal
+      def value_domain = ::Numeric
+
+      def subset_of(other)
+        return Relation::PROVEN if equivalent?(other)
+
+        other.subset_from_numeric_literal(self)
+      end
+
+      def overlap(other)
+        return Relation::PROVEN if equivalent?(other)
+
+        other.overlap_with_numeric_literal(self)
+      end
+    end
+
+    class Nominal < Node
+      def kind = :nominal
+      def nominal? = true
+      def matcher_domain = raw.is_a?(::Class) ? [raw] : []
+      def matches_value(candidate) = Relation.from(raw === candidate)
+
+      def error_message
+        raw.is_a?(::Class) ? "Must be a #{raw}" : super
+      end
+
+      def subset_of(other)
+        return Relation::PROVEN if equivalent?(other)
+
+        other.subset_from_nominal(self)
+      end
+
+      def subset_from_nominal(other) = Relation.from((other.raw <= raw) == true)
+      def subset_from_literal(other) = matches_value(other.raw)
+      def subset_from_numeric_literal(_other) = SemanticMatcher.wrap(::Numeric).subset_of(self)
+      def subset_from_finite_set(other) = other.members_match(self)
+      def subset_from_range(other) = other.endpoints_within(self)
+
+      def subset_from_pattern(other)
+        Relation.all(other.matcher_domain.map { |domain| SemanticMatcher.wrap(domain).subset_of(self) })
+      end
+
+      def overlap(other)
+        return Relation::PROVEN if equivalent?(other)
+
+        other.overlap_with_nominal(self)
+      end
+
+      def overlap_with_nominal(other)
+        return Relation::PROVEN if subset_from_nominal(other).proven? || other.subset_from_nominal(self).proven?
+        return Relation::DISPROVEN if raw.is_a?(::Class) && other.raw.is_a?(::Class)
+
+        Relation::UNKNOWN # unrelated mixins may share an implementing class
+      end
+
+      def overlap_with_literal(other) = Relation.from(other.raw.is_a?(raw))
+      def overlap_with_range(other) = other.overlap_with_nominal(self)
+      def overlap_with_pattern(other) = other.overlap_with_nominal(self)
+    end
+
+    class FiniteSet < Node
+      def kind = :finite_set
+      def matcher_domain = raw.map(&:class).uniq
+      def matches_value(candidate) = Relation.from(raw === candidate)
+
+      def subset_of(other)
+        return Relation::PROVEN if equivalent?(other)
+
+        other.subset_from_finite_set(self)
+      end
+
+      def subset_from_literal(other) = matches_value(other.raw)
+      def subset_from_numeric_literal(_other) = Relation::DISPROVEN
+      def subset_from_finite_set(other) = Relation.from(other.raw.subset?(raw))
+
+      def members_match(other)
+        Relation.all(raw.map { |member| other.matches_value(member) })
+      end
+
+      def overlap(other)
+        return Relation::PROVEN if equivalent?(other)
+
+        other.overlap_with_finite_set(self)
+      end
+
+      def overlap_with_finite_set(other)
+        Relation.from(!(raw & other.raw).empty?)
+      end
+
+      def intersect(other) = other.intersect_with_finite_set(self)
+
+      def intersect_with_finite_set(other)
+        merged = raw & other.raw
+        merged.empty? ? Merge::EMPTY : Merge.merged(self.class.new(merged))
+      end
+    end
+
+    class Interval < Node
+      def kind = :range
+
+      def matcher_domain
+        endpoint = raw.begin || raw.end
+        endpoint.nil? ? [] : [SemanticMatcher.value_domain(endpoint)]
+      end
+
+      def matches_value(candidate) = Relation.from(raw === candidate)
+      def error_message = "Must be within #{raw}"
+
+      def subset_of(other)
+        return Relation::PROVEN if equivalent?(other)
+
+        other.subset_from_range(self)
+      end
+
+      def subset_from_literal(other) = matches_value(other.raw)
+      def subset_from_finite_set(other) = other.members_match(self)
+
+      def subset_from_range(other)
+        lo = if raw.begin.nil?
+               Relation::PROVEN
+             elsif other.raw.begin.nil?
+               Relation::DISPROVEN
+             else
+               Relation.from(raw.cover?(other.raw.begin))
+             end
+        Relation.all([lo, other.end_within(self)])
+      rescue ::ArgumentError, ::TypeError
+        Relation::UNKNOWN
+      end
+
+      def endpoints_within(nominal)
+        endpoints = [raw.begin, raw.end].compact
+        return Relation::UNKNOWN if endpoints.empty?
+
+        Relation.all(endpoints.map { |endpoint| nominal.matches_value(endpoint) })
+      end
+
+      def end_within(outer)
+        return Relation::PROVEN if outer.raw.end.nil?
+        return Relation::DISPROVEN if raw.end.nil?
+
+        cmp = raw.end <=> outer.raw.end
+        return Relation::UNKNOWN if cmp.nil?
+
+        Relation.from(!raw.exclude_end? && outer.raw.exclude_end? ? cmp.negative? : cmp <= 0)
+      end
+
+      def overlap(other)
+        return Relation::PROVEN if equivalent?(other)
+
+        other.overlap_with_range(self)
+      end
+
+      def overlap_with_nominal(other)
+        endpoint = raw.begin || raw.end
+        endpoint.nil? ? Relation::UNKNOWN : other.matches_value(endpoint)
+      end
+
+      def overlap_with_literal(other) = matches_value(other.raw)
+
+      def overlap_with_range(other)
+        merged = intersect_with_range(other)
+        return Relation::DISPROVEN if merged.empty?
+        return Relation::PROVEN if merged.merged?
+
+        Relation::UNKNOWN
+      end
+
+      def intersect(other) = other.intersect_with_range(self)
+
+      def intersect_with_range(other)
+        ab = raw.begin
+        bb = other.raw.begin
+        new_begin = ab.nil? ? bb : (bb.nil? ? ab : (ab >= bb ? ab : bb))
+        ae = raw.end
+        be = other.raw.end
+        new_end, new_exclude =
+          if ae.nil? then [be, other.raw.exclude_end?]
+          elsif be.nil? then [ae, raw.exclude_end?]
+          elsif ae < be then [ae, raw.exclude_end?]
+          elsif be < ae then [be, other.raw.exclude_end?]
+          else [ae, raw.exclude_end? || other.raw.exclude_end?]
+          end
+        unless new_begin.nil? || new_end.nil?
+          return Merge::EMPTY if new_begin > new_end
+          return Merge::EMPTY if new_begin == new_end && new_exclude
+        end
+        Merge.merged(self.class.new(::Range.new(new_begin, new_end, new_exclude)))
+      rescue ::ArgumentError, ::TypeError
+        Merge::UNKNOWN
+      end
+    end
+
+    class Pattern < Node
+      def kind = :pattern
+      def matcher_domain = [::String, ::Symbol]
+      def matches_value(candidate) = Relation.from(raw === candidate)
+
+      def subset_of(other)
+        return Relation::PROVEN if equivalent?(other)
+
+        other.subset_from_pattern(self)
+      end
+
+      def subset_from_text_literal(other) = matches_value(other.raw.to_s)
+
+      def overlap(other)
+        return Relation::PROVEN if equivalent?(other)
+
+        other.overlap_with_pattern(self)
+      end
+
+      def overlap_with_nominal(other)
+        Relation.any(matcher_domain.map { |domain| SemanticMatcher.wrap(domain).overlap(other) })
+      end
+
+      def overlap_with_literal(other)
+        return Relation::UNKNOWN unless other.is_a?(TextLiteral)
+
+        matches_value(other.raw.to_s)
+      end
+    end
+
+    module_function
+
+    # The only raw-class normalization switch. Core algebra receives nodes.
+    def wrap(raw)
+      return raw if raw.is_a?(Node)
+
+      case raw
+      when ::Module then Nominal.new(raw)
+      when ::Range then Interval.new(raw)
+      when ::Set then FiniteSet.new(raw)
+      when ::Regexp then Pattern.new(raw)
+      when ::Numeric then NumericLiteral.new(raw)
+      when ::String, ::Symbol then TextLiteral.new(raw)
+      when ::TrueClass, ::FalseClass, ::NilClass then Literal.new(raw)
+      when ::Array, ::Hash then CollectionMatcher.new(raw)
+      else Opaque.new(raw)
+      end
+    end
+
+    def value_domain(raw) = wrap(raw).value_domain
+    def matcher_domain(raw) = wrap(raw).matcher_domain
+    def singleton?(raw) = wrap(raw).singleton?
+    def nominal?(raw) = wrap(raw).nominal?
+    def error_message(raw) = wrap(raw).error_message
+
+    def merge(left, right)
+      wrap(left).intersect(wrap(right))
+    end
+
+  end
+  private_constant :SemanticMatcher
+end

data/lib/plumb/static_class.rb

@@ -20,8 +20,27 @@ module Plumb
       self.class.new(value)
     end
 
+    # A static step ignores its input and always emits a fixed value. Its input
+    # is therefore Any — it accepts anything, so it opts out of #>> checks on
+    # the input side (eg. as the right of `Undefined >> Static[x]`). Its output
+    # is the value itself (the default #output_type — this atomic node wraps
+    # the value), so a successor that could never accept that value is caught
+    # at composition time, eg. `Types::Static['foo'] >> Types::Integer` raises.
+    def input_type = Types::Any
+
+    # Tests the concrete produced value directly. Atomic matcher logic is unsuitable
+    # here because it models matched values and widens numeric equality domains.
+    # @param other [Composable]
+    # @return [Boolean]
+    def subtype_of?(other)
+      return true if self == other
+      return super if @value.is_a?(Composable)
+
+      other === @value
+    end
+
     def call(result)
-      result.valid(@value)
+      result.valid!(@value)
     end
 
     private