plumb 0.2.0.beta.3 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c347e5312c27a5db7f2c1f668676028fb2613a7b5f459ac5f2d558577599cbd0
-  data.tar.gz: 360a9c7eb0ece5c922eb0447c952a5b449e8164892386d49c781eaf66448e9be
+  metadata.gz: 3c32b91fda7581018e0febe58953ab0256b9850d9848cfe9ba468ef81d6003e3
+  data.tar.gz: 340f1681daffc709e724254a9ee031f1fd0bc12c2cdd80e53f47ce1384e5827c
 SHA512:
-  metadata.gz: a55f939ef7a815cc1a49be1f7c9dcb15e3ebefcb5c2ee4e2256cb157f85c90f4dda64a0316d5e9afb22566ccac236960fcab2103b25e92ba17aff41971f3c884
-  data.tar.gz: e4b5480376bbcc9904404eea5215b7edabfdb3eb8c439eeae96108a597061f6de338bcdeab5edf667a4f2cdf149761fbe64d7f4e2cd7af3ed1bdab779a01259a
+  metadata.gz: e6e3c5d2bbaeeae28946cbaef50bf65edc9d98815d0546e8d62a69a0097dc889448e8edc68863f44ff922f5a808fbdb1266cc8fde6569bcde52c713c80856df7
+  data.tar.gz: ea269dc275559ccb3fb61c94311707881cc11151cbbb433daafb4040218748d33e5461b84be951d73bdc4b5c02ec5ef5622498ea0ac23efa77efcc110411670f

data/README.md

@@ -96,7 +96,7 @@ StringToInt.parse('100lol') # fails
 
 ### `#resolve(value) => Result`
 
-`#resolve` takes an input value and returns a `Result::Valid` or `Result::Invalid`
+`#resolve` takes an input value and returns a `Plumb::Result`, which is either valid or invalid (check with `#valid?` / `#invalid?`).
 
 ```ruby
 result = Types::Integer.resolve(10)
@@ -846,14 +846,14 @@ Example: parsing strings with `Date.parse` and turning `Date::Error` exceptions
 ```ruby
 # Accept a string that can be parsed into a Date
 # via Date.parse
-# If Date.parse raises a Date::Error, return a Result::Invalid with
+# If Date.parse raises a Date::Error, return an invalid Result with
 # the exception's message as error message.
 type = Types::String
 	.build(::Date, :parse)
 	.policy(:rescue, ::Date::Error)
 
-type.resolve('2024-02-02') # => Result::Valid with Date object
-type.resolve('2024-') # => Result::Invalid with error message
+type.resolve('2024-02-02') # => valid Result with Date object
+type.resolve('2024-') # => invalid Result with error message
 ```
 
 The guard keeps the type it wraps: the example above is still a `Date` for subtyping,
@@ -1216,9 +1216,9 @@ Plumb::JSONSchemaVisitor.call(Types::Range[0...100], root: false)
 
 ## `Types::SymbolizedHash`
 
-This type turns a hash's keys into symbols by calling `#to_sym` on them, and returning a new Hash.
+This type recursively turns a hash's String keys into symbols, returning a new Hash. Symbol keys and any other keys pass through unchanged, so it accepts any Hash.
 
-`SymbolizedHash` is a `Symbol => Any` map. You can use it as a _transform_.
+You can use it as a _transform_.
 
 ```ruby
 UserHash = Types::Hash[name: String]
@@ -1233,6 +1233,13 @@ type = Types::Hash[name: String, age: Integer].symbolized
 type.parse('name' => 'Joe', 'age' => 20) # {name: 'Joe', age: 20}
 ```
 
+Hash maps support `#symbolized` too. It raises `Plumb::TypeError` if the map's key type can't accept Symbols, since every symbolized key would be rejected.
+
+```ruby
+Types::Hash[Symbol, Integer].symbolized.parse('a' => 1) # {a: 1}
+Types::Hash[String, Integer].symbolized # raises Plumb::TypeError
+```
+
 ##  maps
 
 You can also use Hash syntax to define a hash map with specific types for all keys and values:
@@ -1361,7 +1368,7 @@ TODO: pluggable concurrency engines (Async?)
 
 ### `#stream`
 
-Turn an Array definition into an enumerator that yields each element wrapped in `Result::Valid` or `Result::Invalid`.
+Turn an Array definition into an enumerator that yields each element wrapped in a valid or invalid `Result`.
 
 See [`Types::Stream`](#typesstream) below for more.
 
@@ -1421,7 +1428,7 @@ Row = Types::Tuple[Types::String.present, Types:Lax::Integer]
 Stream = Types::Stream[Row]
 
 data = CSV.new(File.new('./big-file.csv')).each # An Enumerator
-# stream is an Enumerator that yields rows wrapped in[Result::Valid] or [Result::Invalid]
+# stream is an Enumerator that yields rows wrapped in a valid or invalid Result
 stream = Stream.parse(data)
 stream.each.with_index(1) do |result, line|
   if result.valid?
@@ -1816,7 +1823,7 @@ CreateIfJoe = IsJoe >> CreateUser
 Use `#around` in a pipeline definition to add a middleware step that wraps all other steps registered.
 
 ```ruby
-# The #around interface is #call(Step, Result::Valid) => Result::Valid | Result::Invalid
+# The #around interface is #call(Step, Result) => Result
 StepLogger = proc do |step, result|
   Logger.info "Processing step #{step}"
   step.call(result)
@@ -2170,12 +2177,14 @@ Things to know:
 Every Plumb type exposes the following one-method interface:
 
 ```
-#call(Result::Valid) => Result::Valid | Result::Invalid
+#call(Result) => Result
 ```
 
+The incoming result is always valid (invalid results halt a pipeline before reaching later steps). Return a valid result to pass a value on, or an invalid one to halt.
+
 As long as an object implements this interface, it can be composed into Plumb workflows.
 
-The `Result::Valid` class has helper methods `#valid(value) => Result::Valid` and `#invalid(errors:) => Result::Invalid` to facilitate returning valid or invalid values from your own steps.
+`Plumb::Result` has helper methods `#valid(value) => Result` and `#invalid(value, errors:) => Result` to facilitate returning valid or invalid results from your own steps. Both return a new `Result` and leave the receiver untouched.
 
 ### Compose procs or lambdas directly
 
@@ -2243,7 +2252,7 @@ LoudGreeting = Greeting.default('no greeting').invoke(:upcase)
 
 ### A custom `#call` class
 
-Or write a custom class that responds to `#call(Result::Valid) => Result::Valid | Result::Invalid`
+Or write a custom class that responds to `#call(Result) => Result`
 
 ```ruby
 class Greeting
@@ -2252,8 +2261,8 @@ class Greeting
   end
 
   # The Plumb step interface
-  # @param result [Plumb::Result::Valid]
-  # @return [Plumb::Result::Valid, Plumb::Result::Invalid]
+  # @param result [Plumb::Result] a valid result
+  # @return [Plumb::Result]
   def call(result)
     result.valid("#{@gr} #{result.value}")
   end

data/lib/plumb/and.rb

@@ -29,11 +29,20 @@ module Plumb
       #
       # Conjunction.build, not Intersection.new — `left.output_type` need not preserve
       # values (a record drops undeclared keys, a Static replaces it), and only the
-      # classifier may decide. The `lo.equal?(left)` guard is the fixpoint: a left that
-      # IS its own output type would otherwise recurse forever.
+      # classifier may decide.
+      #
+      # A left that IS its own output type (eg. a recursive type) can't be met without
+      # recursing forever, so fall back to the right alone: every output passed it
+      # unchanged, so it's a sound over-approximation. Unless the right is the Any top,
+      # which would opt the chain out of #>> checks; then stay opaque (self).
       @output_type = if Plumb::Subtyping.value_preserving?(right)
                        lo = left.output_type
-                       lo.equal?(left) ? self : Conjunction.build(lo, right)
+                       if lo.equal?(left)
+                         ro = right.output_type
+                         ro.is_a?(AnyClass) ? self : ro
+                       else
+                         Conjunction.build(lo, right)
+                       end
                      else
                        right.output_type
                      end

data/lib/plumb/hash_map.rb

@@ -35,6 +35,15 @@ module Plumb
       super
     end
 
+    # A map whose key and value types both admit Any is the "any Hash" type, so it
+    # claims anything whose base types are all Hashes (eg. `transform(::Hash)`).
+    def supertype_of?(other)
+      return false unless children.all? { |c| Plumb::Subtyping.subtype?(Types::Any, c) }
+
+      bases = Plumb.resolve_base_types(other)
+      bases.any? && bases.all? { |k| k.is_a?(::Class) && k <= ::Hash }
+    end
+
     # A HashMap re-maps each key and value through its key/value types, so it
     # preserves the value only when both do (a coercing key or value would change
     # the hash).
@@ -74,6 +83,19 @@ module Plumb
       FilteredHashMap.new(@key_type, @value_type)
     end
 
+    # Symbolize keys (via Types::SymbolizedHash), then validate against this map.
+    # Only the key type is checked up front: a map whose keys can't be Symbols
+    # (eg. `Hash[String, X]`) would reject every symbolized key.
+    # @see HashClass#symbolized
+    # @raise [Plumb::TypeError] when the key type doesn't accept Symbols.
+    def symbolized
+      unless Plumb::Subtyping.subtype?(Types::Symbol, Plumb::Subtyping.accepted_type(@key_type))
+        raise Plumb::TypeError, "cannot symbolize #{inspect}: its key type doesn't accept Symbols"
+      end
+
+      Types::SymbolizedHash / self
+    end
+
     private def _inspect = "HashMap[#{@key_type.inspect}, #{@value_type.inspect}]"
 
     # Same key/value types as a HashMap (so it inherits #initialize, #children

data/lib/plumb/subtyping.rb

@@ -72,8 +72,7 @@ module Plumb
       ub = unwrap_transparent(b)
       return subtype?(ua, ub) unless ua.equal?(a) && ub.equal?(b)
 
-      return true if b.is_a?(AnyClass)  # X <= Top
-      return false if a.is_a?(AnyClass) # Top <= X only when X is Top (handled above)
+      return true if b.is_a?(AnyClass) # X <= Top
 
       # A value-converting type (Function, or any custom type that opts in) is
       # identified for subtyping by what it *produces*, not what it consumes, so we
@@ -108,6 +107,10 @@ module Plumb
       return b.children.all? { |bb| subtype?(a, bb) } if b.is_a?(Intersection) # a <= (b1 ∧ b2)
       return a.children.any? { |aa| subtype?(aa, b) } if a.is_a?(Intersection) # (a1 ∧ a2) <= b
 
+      # Top <= X only when X is Top-equivalent. Checked after the join/meet rules
+      # so a union with a Top branch (`X | Any`) still admits Top.
+      return false if a.is_a?(AnyClass)
+
       # `a` decides via its #subtype_of? leaf; if it can't (it doesn't know about
       # `b`), `b` may claim `a` via #supertype_of? — the mirror hook for
       # supertype-driven relations like Interface duck-typing.

data/lib/plumb/types.rb

@@ -196,8 +196,8 @@ module Plumb
     # @example Mixed types preserved
     #   SymbolizedHash.parse({ 'count' => 1, 'active' => true })  # => { count: 1, active: true }
     SymbolizedHash = Hash[
-      # String keys are converted to symbols, existing symbols are preserved
-      (Symbol | String.transform(::Symbol, :to_sym)),
+      # String keys are converted to symbols; any other key passes through unchanged
+      (Symbol | String.transform(::Symbol, :to_sym) | Any),
       # Hash values are recursively symbolized, other types pass through unchanged
       Any.defer { SymbolizedHash } | Any
     ]

data/lib/plumb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Plumb
-  VERSION = '0.2.0.beta.3'
+  VERSION = '0.3.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: plumb
 version: !ruby/object:Gem::Version
-  version: 0.2.0.beta.3
+  version: 0.3.1
 platform: ruby
 authors:
 - Ismael Celis