plumb 0.0.2 → 0.0.3

data/lib/plumb/json_schema_visitor.rb

@@ -12,12 +12,17 @@ module Plumb
     DEFAULT = 'default'
     ANY_OF = 'anyOf'
     ALL_OF = 'allOf'
+    NOT = 'not'
     ENUM = 'enum'
     CONST = 'const'
     ITEMS = 'items'
     PATTERN = 'pattern'
     MINIMUM = 'minimum'
     MAXIMUM = 'maximum'
+    MIN_ITEMS = 'minItems'
+    MAX_ITEMS = 'maxItems'
+    MIN_LENGTH = 'minLength'
+    MAX_LENGTH = 'maxLength'
 
     def self.call(node)
       {
@@ -78,7 +83,7 @@ module Plumb
     end
 
     on(:not) do |node, props|
-      props.merge('not' => visit(node.step))
+      props.merge(NOT => visit(node.step))
     end
 
     on(:value) do |node, props|
@@ -113,14 +118,52 @@ module Plumb
       visit(node.value, props)
     end
 
-    on(:rules) do |node, props|
-      node.rules.reduce(props) do |acc, rule|
-        acc.merge(visit(rule))
+    on(:policy) do |node, props|
+      props = visit(node.step, props)
+      method_name = :"visit_#{node.policy_name}_policy"
+      if respond_to?(method_name)
+        send(method_name, node, props)
+      else
+        props
       end
     end
 
-    on(:rule_included_in) do |node, props|
-      props.merge(ENUM => node.arg_value)
+    on(:options_policy) do |node, props|
+      props.merge(ENUM => node.arg)
+    end
+
+    on(:size_policy) do |node, props|
+      opts = {}
+      case props[TYPE]
+      when 'array'
+        case node.arg
+        when Range
+          opts[MIN_ITEMS] = node.arg.min if node.arg.begin
+          opts[MAX_ITEMS] = node.arg.max if node.arg.end
+        when Numeric
+          opts[MIN_ITEMS] = node.arg
+          opts[MAX_ITEMS] = node.arg
+        end
+      when 'string'
+        case node.arg
+        when Range
+          opts[MIN_LENGTH] = node.arg.min if node.arg.begin
+          opts[MAX_LENGTH] = node.arg.max if node.arg.end
+        when Numeric
+          opts[MIN_LENGTH] = node.arg
+          opts[MAX_LENGTH] = node.arg
+        end
+      end
+
+      props.merge(opts)
+    end
+
+    on(:excluded_from_policy) do |node, props|
+      props.merge(NOT => { ENUM => node.arg })
+    end
+
+    on(Proc) do |_node, props|
+      props
     end
 
     on(:match) do |node, props|

data/lib/plumb/match_class.rb

@@ -8,11 +8,12 @@ module Plumb
 
     attr_reader :matcher
 
-    def initialize(matcher = Undefined, error: nil)
+    def initialize(matcher = Undefined, error: nil, label: nil)
       raise TypeError 'matcher must respond to #===' unless matcher.respond_to?(:===)
 
       @matcher = matcher
       @error = error.nil? ? build_error(matcher) : (error % matcher)
+      @label = matcher.is_a?(Class) ? matcher.inspect : "Match(#{label || @matcher.inspect})"
       freeze
     end
 
@@ -22,9 +23,7 @@ module Plumb
 
     private
 
-    def _inspect
-      @matcher.inspect
-    end
+    def _inspect = @label
 
     def build_error(matcher)
       case matcher

data/lib/plumb/metadata_visitor.rb

@@ -77,7 +77,12 @@ module Plumb
     end
 
     on(:static) do |node, props|
-      props.merge(static: node.value)
+      type = node.value.is_a?(Class) ? node.value : node.value.class
+      props.merge(static: node.value, type:)
+    end
+
+    on(:policy) do |node, props|
+      visit(node.step, props).merge(node.policy_name => node.arg)
     end
 
     on(:rules) do |node, props|
@@ -117,5 +122,9 @@ module Plumb
     on(:tagged_hash) do |_node, props|
       props.merge(type: Hash)
     end
+
+    on(Proc) do |_node, props|
+      props
+    end
   end
 end

data/lib/plumb/policies.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'plumb/policies'
+
+module Plumb
+  # A policy registry for Plumb
+  # It holds and gets registered policies.
+  # Policies are callable objects that act as factories for type compositions.
+  class Policies
+    UnknownPolicyError = Class.new(StandardError)
+    MethodAlreadyDefinedError = Class.new(StandardError)
+
+    def initialize
+      @policies = {}
+    end
+
+    # Register a policy for all or specific outpyt types.
+    # Example for a policy that works for all types:
+    #   #register(Object, :my_policy, ->(node, arg) { ... })
+    # Example for a policy that works for a specific type:
+    #   #register(String, :my_policy, ->(node, arg) { ... })
+    # Example for a policy that works for a specific interface:
+    #   #register(:size, :my_policy, ->(node, arg) { ... })
+    #
+    # The policy callable takes the step it is applied to, a policy argument (if any) and a policy block (if any).
+    # Example for a policy #default(default_value = Undefined) { 'some-default-value' }
+    #   policy = proc do |type, default_value = Undefined, &block|
+    #     type | (Plumb::Types::Undefined >> Plumb::Types::Static[default_value])
+    #   end
+    #
+    # @param for_type [Class, Symbol] the type the policy is for.
+    # @param name [Symbol] the name of the policy.
+    # @param policy [Proc] the policy to register.
+    def register(for_type, name, policy)
+      @policies[name] ||= {}
+      @policies[name][for_type] = policy
+    end
+
+    # Get a policy for a given type.
+    # @param types [Array<Class>] the types
+    # @param name [Symbol] the policy name
+    # @return [#call] the policy callable
+    # @raise [UnknownPolicyError] if the policy is not registered for the given types
+    def get(types, name)
+      if (pol = resolve_shared_policy(types, name))
+        pol
+      elsif (pol = @policies.dig(name, Object))
+        raise UnknownPolicyError, "Unknown policy #{name} for #{types.inspect}" unless pol
+
+        pol
+      else
+        raise UnknownPolicyError, "Unknown or incompatible policy #{name} for #{types.inspect}"
+      end
+    end
+
+    private
+
+    def resolve_shared_policy(types, name)
+      pols = types.map do |type|
+        resolve_policy(type, name)
+      end.uniq
+      pols.size == 1 ? pols.first : nil
+    end
+
+    def resolve_policy(type, name)
+      policies = @policies[name]
+      return nil unless policies
+
+      # { Object => policy1, String => policy2, size: policy3 }
+      #
+      policies.find do |for_type, _pol|
+        case for_type
+        when Symbol # :size
+          type.instance_methods.include?(for_type)
+        when Class # String
+          for_type == type
+        end
+      end&.last
+    end
+  end
+end

data/lib/plumb/policy.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'plumb/steppable'
+
+module Plumb
+  # Wrap a policy composition ("step") in a Policy object.
+  # So that visitors such as JSONSchema and Metadata visitors
+  # can define dedicated handlers for policies, if they need to.
+  class Policy
+    include Steppable
+
+    attr_reader :policy_name, :arg, :step
+
+    # @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.
+    def initialize(policy_name, arg, step)
+      @policy_name = policy_name
+      @arg = arg
+      @step = step
+      freeze
+    end
+
+    # The standard Step interface.
+    # @param result [Result::Valid]
+    # @return [Result::Valid, Result::Invalid]
+    def call(result) = @step.call(result)
+
+    private def _inspect = @step.inspect
+  end
+end

data/lib/plumb/schema.rb

@@ -172,8 +172,8 @@ module Plumb
         self
       end
 
-      def rule(...)
-        @_type = @_type.rule(...)
+      def policy(...)
+        @_type = @_type.policy(...)
         self
       end
 

data/lib/plumb/steppable.rb

@@ -10,6 +10,7 @@ module Plumb
 
     def to_s = inspect
     def node_name = :undefined
+    def empty? = true
   end
 
   TypeError = Class.new(::TypeError)
@@ -111,7 +112,7 @@ module Plumb
     end
 
     def check(errors = 'did not pass the check', &block)
-      self >> MatchClass.new(block, error: errors)
+      self >> MatchClass.new(block, error: errors, label: errors)
     end
 
     def meta(data = {})
@@ -136,22 +137,6 @@ module Plumb
 
     def [](val) = match(val)
 
-    DefaultProc = proc do |callable|
-      proc do |result|
-        result.valid(callable.call)
-      end
-    end
-
-    def default(val = Undefined, &block)
-      val_type = if val == Undefined
-                   DefaultProc.call(block)
-                 else
-                   Types::Static[val]
-                 end
-
-      self | (Types::Undefined >> val_type)
-    end
-
     class Node
       include Steppable
 
@@ -171,29 +156,28 @@ module Plumb
       Node.new(node_name, self, metadata)
     end
 
-    def nullable
-      Types::Nil | self
-    end
-
-    def present
-      Types::Present >> self
-    end
-
-    def options(opts = [])
-      rule(included_in: opts)
-    end
+    # Register a policy for this step.
+    # Mode 1.a: #policy(:name, arg) a single policy with an argument
+    # Mode 1.b: #policy(:name) a single policy without an argument
+    # Mode 2: #policy(p1: value, p2: value) multiple policies with arguments
+    # The latter mode will be expanded to multiple #policy calls.
+    # @return [Step]
+    def policy(*args, &blk)
+      case args
+      in [::Symbol => name, *rest] # #policy(:name, arg)
+        types = Array(metadata[:type]).uniq
 
-    def rule(*args)
-      specs = case args
-              in [::Symbol => rule_name, value]
-                { rule_name => value }
-              in [::Hash => rules]
-                rules
-              else
-                raise ArgumentError, "expected 1 or 2 arguments, but got #{args.size}"
-              end
+        bargs = [self]
+        bargs << rest.first if rest.any?
+        block = Plumb.policies.get(types, name)
+        pol = block.call(*bargs, &blk)
 
-      self >> Rules.new(specs, metadata[:type])
+        Policy.new(name, rest.first, pol)
+      in [::Hash => opts] # #policy(p1: value, p2: value)
+        opts.reduce(self) { |step, (name, value)| step.policy(name, value) }
+      else
+        raise ArgumentError, "expected a symbol or hash, got #{args.inspect}"
+      end
     end
 
     def ===(other)
@@ -217,7 +201,7 @@ module Plumb
       inspect
     end
 
-    # Build a step that will invoke onr or more methods on the value.
+    # Build a step that will invoke one or more methods on the value.
     # Ex 1: Types::String.invoke(:downcase)
     # Ex 2: Types::Array.invoke(:[], 1)
     # Ex 3 chain of methods: Types::String.invoke([:downcase, :to_sym])
@@ -240,5 +224,6 @@ end
 
 require 'plumb/deferred'
 require 'plumb/transform'
+require 'plumb/policy'
 require 'plumb/build'
 require 'plumb/metadata'

data/lib/plumb/types.rb

@@ -3,25 +3,127 @@
 require 'bigdecimal'
 
 module Plumb
-  Rules.define :included_in, 'elements must be included in %<value>s', expects: ::Array do |result, opts|
-    result.value.all? { |v| opts.include?(v) }
+  # Define core policies
+  # Allowed options for an array type.
+  # It validates that each element is in the options array.
+  # Usage:
+  #   type = Types::Array.options(['a', 'b'])
+  policy :options, helper: true, for_type: ::Array do |type, opts|
+    type.check("must be included in #{opts.inspect}") do |v|
+      v.all? { |val| opts.include?(val) }
+    end
+  end
+
+  # Generic options policy for all other types.
+  # Usage:
+  #   type = Types::String.options(['a', 'b'])
+  policy :options do |type, opts|
+    type.check("must be included in #{opts.inspect}") do |v|
+      opts.include?(v)
+    end
+  end
+
+  # Validate that array elements are NOT in the options array.
+  # Usage:
+  #   type = Types::Array.policy(excluded_from: ['a', 'b'])
+  policy :excluded_from, for_type: ::Array do |type, opts|
+    type.check("must not be included in #{opts.inspect}") do |v|
+      v.none? { |val| opts.include?(val) }
+    end
+  end
+
+  # Usage:
+  #   type = Types::String.policy(excluded_from: ['a', 'b'])
+  policy :excluded_from do |type, opts|
+    type.check("must not be included in #{opts.inspect}") do |v|
+      !opts.include?(v)
+    end
+  end
+
+  # Validate #size against a number or any object that responds to #===.
+  # This works with any type that repsonds to #size.
+  # Usage:
+  #   type = Types::String.policy(size: 10)
+  #   type = Types::Integer.policy(size: 1..10)
+  #   type = Types::Array.policy(size: 1..)
+  #   type = Types::Any[Set].policy(size: 1..)
+  policy :size, for_type: :size do |type, size|
+    type.check("must be of size #{size}") { |v| size === v.size }
   end
-  Rules.define :included_in, 'must be included in %<value>s' do |result, opts|
-    opts.include? result.value
+
+  # Validate that an object is not #empty? nor #nil?
+  # Usage:
+  #   Types::String.present
+  #   Types::Array.present
+  policy :present, helper: true do |type, *_args|
+    type.check('must be present') do |v|
+      if v.respond_to?(:empty?)
+        !v.empty?
+      else
+        !v.nil?
+      end
+    end
   end
-  Rules.define :excluded_from, 'elements must not be included in %<value>s', expects: ::Array do |result, value|
-    result.value.all? { |v| !value.include?(v) }
+
+  # Allow nil values for a type.
+  # Usage:
+  #   nullable_int = Types::Integer.nullable
+  #   nullable_int.parse(nil) # => nil
+  #   nullable_int.parse(10)  # => 10
+  #   nullable_int.parse('nope') # => error: not an Integer
+  policy :nullable, helper: true do |type, *_args|
+    Types::Nil | type
   end
-  Rules.define :excluded_from, 'must not be included in %<value>s' do |result, value|
-    !value.include?(result.value)
+
+  # Validate that a value responds to a method
+  # Usage:
+  #  type = Types::Any.policy(respond_to: :upcase)
+  #  type = Types::Any.policy(respond_to: [:upcase, :strip])
+  policy :respond_to do |type, method_names|
+    type.check("must respond to #{method_names.inspect}") do |value|
+      Array(method_names).all? { |m| value.respond_to?(m) }
+    end
   end
-  Rules.define :respond_to, 'must respond to %<value>s' do |result, value|
-    Array(value).all? { |m| result.value.respond_to?(m) }
+
+  # Return a default value if the input value is Undefined (ie key not present in a Hash).
+  # Usage:
+  #   type = Types::String.default('default')
+  #   type.parse(Undefined) # => 'default'
+  #   type.parse('yes')     # => 'yes'
+  #
+  # Works with a block too:
+  #   date = Type::Any[Date].default { Date.today }
+  #
+  policy :default, helper: true do |type, value = Undefined, &block|
+    val_type = if value == Undefined
+                 Step.new(->(result) { result.valid(block.call) }, 'default proc')
+               else
+                 Types::Static[value]
+               end
+
+    type | (Types::Undefined >> val_type)
   end
-  Rules.define :size, 'must be of size %<value>s', expects: :size do |result, value|
-    value === result.value.size
+
+  # Split a string into an array. Default separator is /\s*,\s*/
+  # Usage:
+  #   type = Types::String.split
+  #   type.parse('a,b,c') # => ['a', 'b', 'c']
+  #
+  # Custom separator:
+  #   type = Types::String.split(';')
+  module SplitPolicy
+    DEFAULT_SEPARATOR = /\s*,\s*/
+
+    def self.call(type, separator = DEFAULT_SEPARATOR)
+      type.invoke(:split, separator) >> Types::Array[String]
+    end
+
+    def self.for_type = ::String
+    def self.helper = false
   end
 
+  policy :split, SplitPolicy
+
   module Types
     extend TypeRegistry
 
@@ -43,17 +145,6 @@ module Plumb
     Tuple = TupleClass.new
     Hash = HashClass.new
     Interface = InterfaceClass.new
-    # TODO: type-speficic concept of blank, via Rules
-    Blank = (
-      Undefined \
-      | Nil \
-      | String.value(BLANK_STRING) \
-      | Hash.value(BLANK_HASH) \
-      | Array.value(BLANK_ARRAY)
-    )
-
-    Present = Blank.invalid(errors: 'must be present')
-    Split = String.transform(::String) { |v| v.split(/\s*,\s*/) }
 
     module Lax
       NUMBER_EXPR = /^\d{1,3}(?:,\d{3})*(?:\.\d+)?$/

data/lib/plumb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Plumb
-  VERSION = '0.0.2'
+  VERSION = '0.0.3'
 end

data/lib/plumb/visitor_handlers.rb

@@ -23,7 +23,12 @@ module Plumb
                     else
                       :"#{(node.is_a?(::Class) ? node : node.class)}_class"
                     end
-      method_name = "visit_#{method_name}"
+
+      visit_name(method_name, node, props)
+    end
+
+    def visit_name(method_name, node, props = BLANK_HASH)
+      method_name = :"visit_#{method_name}"
       if respond_to?(method_name)
         send(method_name, node, props)
       else

data/lib/plumb.rb

@@ -1,6 +1,58 @@
 # frozen_string_literal: true
 
+require 'plumb/policies'
+
 module Plumb
+  @policies = Policies.new
+
+  def self.policies
+    @policies
+  end
+
+  # Register a policy with the given name and block.
+  # Optionally define a method on the Steppable method to call the policy.
+  # Example:
+  #   Plumb.policy(:multiply_by, for_type: Integer, helper: true) do |step, factor, &block|
+  #     step.transform(Integer) { |number| number * factor }
+  #   end
+  #
+  #  type = Types::Integer.multiply_by(2)
+  #  type.parse(10) # => 20
+  #
+  # @param name [Symbol] the name of the policy
+  # @param opts [Hash] options for the policy
+  # @yield [Step, Object, &block] the step (type), policy argument, and policy block, if any.
+  def self.policy(name, opts = {}, &block)
+    name = name.to_sym
+    if opts.is_a?(Hash) && block_given?
+      for_type = opts[:for_type] || Object
+      helper = opts[:helper] || false
+    elsif opts.respond_to?(:call) && opts.respond_to?(:for_type) && opts.respond_to?(:helper)
+      for_type = opts.for_type
+      helper = opts.helper
+      block = opts.method(:call)
+    else
+      raise ArgumentError, 'Expected a block or a hash with :for_type and :helper keys'
+    end
+
+    policies.register(for_type, name, block)
+
+    return self unless helper
+
+    if Steppable.instance_methods.include?(name)
+      raise Policies::MethodAlreadyDefinedError, "Method #{name} is already defined on Steppable"
+    end
+
+    Steppable.define_method(name) do |arg = Undefined, &bl|
+      if arg == Undefined
+        policy(name, &bl)
+      else
+        policy(name, arg, &bl)
+      end
+    end
+
+    self
+  end
 end
 
 require 'plumb/result'
@@ -10,7 +62,6 @@ require 'plumb/any_class'
 require 'plumb/step'
 require 'plumb/and'
 require 'plumb/pipeline'
-require 'plumb/rules'
 require 'plumb/static_class'
 require 'plumb/value_class'
 require 'plumb/match_class'

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: plumb
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Ismael Celis
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-11 00:00:00.000000000 Z
+date: 2024-07-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: concurrent-ruby
+  name: bigdecimal
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -25,7 +25,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: bigdecimal
+  name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -53,6 +53,7 @@ files:
 - examples/command_objects.rb
 - examples/concurrent_downloads.rb
 - examples/csv_stream.rb
+- examples/env_config.rb
 - examples/programmers.csv
 - examples/weekdays.rb
 - lib/plumb.rb
@@ -72,8 +73,9 @@ files:
 - lib/plumb/not.rb
 - lib/plumb/or.rb
 - lib/plumb/pipeline.rb
+- lib/plumb/policies.rb
+- lib/plumb/policy.rb
 - lib/plumb/result.rb
-- lib/plumb/rules.rb
 - lib/plumb/schema.rb
 - lib/plumb/static_class.rb
 - lib/plumb/step.rb
@@ -87,7 +89,7 @@ files:
 - lib/plumb/value_class.rb
 - lib/plumb/version.rb
 - lib/plumb/visitor_handlers.rb
-homepage: ''
+homepage: https://github.com/ismasan/plumb
 licenses:
 - MIT
 metadata: {}