teckel 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18179b7fd315a11bc51f0ac4cfbdba4c0e74ad82a6a7dc186289433906ec2783
-  data.tar.gz: 02eb5f5c59ac9983a92b457f9253a38f9188e3f2b17d4f30029aa545b3151181
+  metadata.gz: bf2c470202a0d90fbc79ed7d6c7e065634f34f6237d01d8d9772489f7ba43e94
+  data.tar.gz: 0b2937e820b2f61bf37d835521c6b981e95e50c3f1ef4d5e968ee38dfea7c5fa
 SHA512:
-  metadata.gz: cbbbebfecccf6806da642dbc1dce843946c7dcaa27abb7c38467b0512ff5cb32d13b848fae0eaa0f8c4641f26e5b1f03f58f82fb70b3aa8aa1a891356698ff16
-  data.tar.gz: b312534680f31d7cff2a13326f3dc3cc01566110d3001b285d233c97548edbfb2fe008d59821ef0723b63687f12e95cca3f06f2f7c1a3f8d0e15d90caca4733d
+  metadata.gz: 3cf2096a7827c2547e6c4cc135657d68dcc597d057e202d0c8cda91753eee09648133e3c6728a3ae1ec14f140fe562b2648ae77439cccfa015a5130326557fba
+  data.tar.gz: 5f13605ac5dc726ce964a85225d1e860a22d00b8eabae78616fa998e77c94ec7251f1367f07175868e8724477bc95c27945d93e23bee0da68303a452a1180e09

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changes
 
+## 0.5.0
+
+- Fix: calling chain with settings and no input [GH-14]
+- Add: Default settings for Operation and Chains [GH-17], [GH-18]
+  ```ruby
+  class MyOperation
+    include Teckel::Operation
+
+    settings Struct.new(:logger) 
+
+    # If your settings class can cope with no input and you want to make sure
+    # `settings` gets initialized and set.
+    # settings will be #<struct logger=nil>
+    default_settings!
+
+    # settings will be #<struct logger=MyGlobalLogger>
+    default_settings!(MyGlobalLogger)
+
+    # settings will be #<struct logger=#<Logger:<...>>
+    default_settings! -> { settings.new(Logger.new("/tmp/my.log")) }
+  end
+
+  class Chain
+    include Teckel::Chain
+
+    # set or overwrite operation settings
+    default_settings!(a: MyOtherLogger)
+
+    step :a, MyOperation
+  end
+  ```
+
+Internal:
+- Move operation and chain config dsl methods into own module [GH-15]
+- Code simplifications [GH-16]
+
 ## 0.4.0
 
 - Moving verbose examples from API docs into github pages

data/lib/teckel/chain.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'chain/config'
 require_relative 'chain/step'
 require_relative 'chain/result'
 require_relative 'chain/runner'
@@ -37,122 +38,6 @@ module Teckel
         end
       end
 
-      # Declare a {Operation} as a named step
-      #
-      # @param name [String,Symbol] The name of the operation.
-      #   This name is used in an error case to let you know which step failed.
-      # @param operation [Operation] The operation to call, which
-      #   must return a {Teckel::Result} object.
-      def step(name, operation)
-        steps << Step.new(name, operation)
-      end
-
-      # Get the list of defined steps
-      #
-      # @return [<Step>]
-      def steps
-        @config.for(:steps) { [] }
-      end
-
-      # Set or get the optional around hook.
-      # A Hook might be given as a block or anything callable. The execution of
-      # the chain is yielded to this hook. The first argument being the callable
-      # chain ({Runner}) and the second argument the +input+ data. The hook also
-      # needs to return the result.
-      #
-      # @param callable [Proc,{#call}] The hook to pass chain execution control to. (nil)
-      #
-      # @return [Proc,{#call}] The configured hook
-      #
-      # @example Around hook with block
-      #   OUTPUTS = []
-      #
-      #   class Echo
-      #     include ::Teckel::Operation
-      #     result!
-      #
-      #     input Hash
-      #     output input
-      #
-      #     def call(hsh)
-      #       hsh
-      #     end
-      #   end
-      #
-      #   class MyChain
-      #     include Teckel::Chain
-      #
-      #     around do |chain, input|
-      #       OUTPUTS << "before start"
-      #       result = chain.call(input)
-      #       OUTPUTS << "after start"
-      #       result
-      #     end
-      #
-      #     step :noop, Echo
-      #   end
-      #
-      #   result = MyChain.call(some: 'test')
-      #   OUTPUTS #=> ["before start", "after start"]
-      #   result.success #=> { some: "test" }
-      def around(callable = nil, &block)
-        @config.for(:around, callable || block)
-      end
-
-      # @!attribute [r] runner()
-      # @return [Class] The Runner class
-      # @!visibility protected
-
-      # Overwrite the default runner
-      # @param klass [Class] A class like the {Runner}
-      # @!visibility protected
-      def runner(klass = nil)
-        @config.for(:runner, klass) { Runner }
-      end
-
-      # @overload result()
-      #   Get the configured result object class wrapping {.error} or {.output}.
-      #   @return [Class] The +result+ class, or {Teckel::Chain::Result} as default
-      #
-      # @overload result(klass)
-      #   Set the result object class wrapping {.error} or {.output}.
-      #   @param klass [Class] The +result+ class
-      #   @return [Class] The +result+ class configured
-      def result(klass = nil)
-        @config.for(:result, klass) { const_defined?(:Result, false) ? self::Result : Teckel::Chain::Result }
-      end
-
-      # @overload result_constructor()
-      #   The callable constructor to build an instance of the +result+ class.
-      #   Defaults to {Teckel::DEFAULT_CONSTRUCTOR}
-      #   @return [Proc] A callable that will return an instance of +result+ class.
-      #
-      # @overload result_constructor(sym_or_proc)
-      #  Define how to build the +result+.
-      #  @param  sym_or_proc [Symbol, #call]
-      #    - Either a +Symbol+ representing the _public_ method to call on the +result+ class.
-      #    - Or anything that response to +#call+ (like a +Proc+).
-      #  @return [#call] The callable constructor
-      #
-      #  @example
-      #    class MyOperation
-      #      include Teckel::Operation
-      #
-      #      class Result < Teckel::Operation::Result
-      #        def initialize(value, success, step, options = {}); end
-      #      end
-      #
-      #      # If you need more control over how to build a new +Settings+ instance
-      #      result_constructor ->(value, success, step) { result.new(value, success, step, {foo: :bar}) }
-      #    end
-      def result_constructor(sym_or_proc = nil)
-        constructor = build_counstructor(result, sym_or_proc) unless sym_or_proc.nil?
-
-        @config.for(:result_constructor, constructor) {
-          build_counstructor(result, Teckel::DEFAULT_CONSTRUCTOR)
-        } || raise(MissingConfigError, "Missing result_constructor config for #{self}")
-      end
-
       # The primary interface to call the chain with the given input.
       #
       # @param input Any form of input the first steps +input+ class can handle
@@ -160,7 +45,15 @@ module Teckel
       # @return [Teckel::Chain::Result] The result object wrapping
       #   the result value, the success state and last executed step.
       def call(input = nil)
-        runner = self.runner.new(self)
+        default_settings = self.default_settings
+
+        runner =
+          if default_settings
+            self.runner.new(self, default_settings)
+          else
+            self.runner.new(self)
+          end
+
         if around
           around.call(runner, input)
         else
@@ -178,81 +71,10 @@ module Teckel
         end
       end
       alias :set :with
-
-      # @!visibility private
-      # @return [void]
-      def define!
-        raise MissingConfigError, "Cannot define Chain with no steps" if steps.empty?
-
-        %i[around runner result result_constructor].each { |e| public_send(e) }
-        steps.each(&:finalize!)
-        nil
-      end
-
-      # Disallow any further changes to this Chain.
-      # @note This also calls +finalize!+ on all Operations defined as steps.
-      #
-      # @return [self] Frozen self
-      # @!visibility public
-      def finalize!
-        define!
-        steps.freeze
-        @config.freeze
-        self
-      end
-
-      # Produces a shallow copy of this chain.
-      # It's {around}, {runner} and {steps} will get +dup+'ed
-      #
-      # @return [self]
-      # @!visibility public
-      def dup
-        dup_config(super)
-      end
-
-      # Produces a clone of this chain.
-      # It's {around}, {runner} and {steps} will get +dup+'ed
-      #
-      # @return [self]
-      # @!visibility public
-      def clone
-        if frozen?
-          super
-        else
-          dup_config(super)
-        end
-      end
-
-      # @!visibility private
-      def inherited(subclass)
-        dup_config(subclass)
-      end
-
-      # @!visibility private
-      def self.extended(base)
-        base.instance_variable_set(:@config, Config.new)
-      end
-
-      private
-
-      def dup_config(other_class)
-        new_config = @config.dup
-        new_config.replace(:steps) { steps.dup }
-
-        other_class.instance_variable_set(:@config, new_config)
-        other_class
-      end
-
-      def build_counstructor(on, sym_or_proc)
-        if sym_or_proc.is_a?(Symbol) && on.respond_to?(sym_or_proc)
-          on.public_method(sym_or_proc)
-        elsif sym_or_proc.respond_to?(:call)
-          sym_or_proc
-        end
-      end
     end
 
     def self.included(receiver)
+      receiver.extend Config
       receiver.extend ClassMethods
     end
   end

data/lib/teckel/chain/config.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module Teckel
+  module Chain
+    module Config
+      # Declare a {Operation} as a named step
+      #
+      # @param name [String,Symbol] The name of the operation.
+      #   This name is used in an error case to let you know which step failed.
+      # @param operation [Operation] The operation to call, which
+      #   must return a {Teckel::Result} object.
+      def step(name, operation)
+        steps << Step.new(name, operation)
+      end
+
+      # Get the list of defined steps
+      #
+      # @return [<Step>]
+      def steps
+        @config.for(:steps) { [] }
+      end
+
+      # Set or get the optional around hook.
+      # A Hook might be given as a block or anything callable. The execution of
+      # the chain is yielded to this hook. The first argument being the callable
+      # chain ({Runner}) and the second argument the +input+ data. The hook also
+      # needs to return the result.
+      #
+      # @param callable [Proc,{#call}] The hook to pass chain execution control to. (nil)
+      #
+      # @return [Proc,{#call}] The configured hook
+      #
+      # @example Around hook with block
+      #   OUTPUTS = []
+      #
+      #   class Echo
+      #     include ::Teckel::Operation
+      #     result!
+      #
+      #     input Hash
+      #     output input
+      #
+      #     def call(hsh)
+      #       hsh
+      #     end
+      #   end
+      #
+      #   class MyChain
+      #     include Teckel::Chain
+      #
+      #     around do |chain, input|
+      #       OUTPUTS << "before start"
+      #       result = chain.call(input)
+      #       OUTPUTS << "after start"
+      #       result
+      #     end
+      #
+      #     step :noop, Echo
+      #   end
+      #
+      #   result = MyChain.call(some: 'test')
+      #   OUTPUTS #=> ["before start", "after start"]
+      #   result.success #=> { some: "test" }
+      def around(callable = nil, &block)
+        @config.for(:around, callable || block)
+      end
+
+      # @!attribute [r] runner()
+      # @return [Class] The Runner class
+      # @!visibility protected
+
+      # Overwrite the default runner
+      # @param klass [Class] A class like the {Runner}
+      # @!visibility protected
+      def runner(klass = nil)
+        @config.for(:runner, klass) { Runner }
+      end
+
+      # @overload result()
+      #   Get the configured result object class wrapping {.error} or {.output}.
+      #   @return [Class] The +result+ class, or {Teckel::Chain::Result} as default
+      #
+      # @overload result(klass)
+      #   Set the result object class wrapping {.error} or {.output}.
+      #   @param klass [Class] The +result+ class
+      #   @return [Class] The +result+ class configured
+      def result(klass = nil)
+        @config.for(:result, klass) { const_defined?(:Result, false) ? self::Result : Teckel::Chain::Result }
+      end
+
+      # @overload result_constructor()
+      #   The callable constructor to build an instance of the +result+ class.
+      #   Defaults to {Teckel::DEFAULT_CONSTRUCTOR}
+      #   @return [Proc] A callable that will return an instance of +result+ class.
+      #
+      # @overload result_constructor(sym_or_proc)
+      #  Define how to build the +result+.
+      #  @param  sym_or_proc [Symbol, #call]
+      #    - Either a +Symbol+ representing the _public_ method to call on the +result+ class.
+      #    - Or anything that response to +#call+ (like a +Proc+).
+      #  @return [#call] The callable constructor
+      #
+      #  @example
+      #    class MyOperation
+      #      include Teckel::Operation
+      #
+      #      class Result < Teckel::Operation::Result
+      #        def initialize(value, success, step, options = {}); end
+      #      end
+      #
+      #      # If you need more control over how to build a new +Settings+ instance
+      #      result_constructor ->(value, success, step) { result.new(value, success, step, {foo: :bar}) }
+      #    end
+      def result_constructor(sym_or_proc = nil)
+        constructor = build_constructor(result, sym_or_proc) unless sym_or_proc.nil?
+
+        @config.for(:result_constructor, constructor) {
+          build_constructor(result, Teckel::DEFAULT_CONSTRUCTOR)
+        } || raise(MissingConfigError, "Missing result_constructor config for #{self}")
+      end
+
+      # Declare default settings operation iin this chain should use when called without
+      # {Teckel::Chain::ClassMethods#with #with}.
+      #
+      # Explicit call-time settings will *not* get merged with declared default setting.
+      #
+      # @param settings [Hash{String,Symbol => Object}] Set settings for a step by it's name
+      #
+      # @example
+      #   class MyOperation
+      #     include Teckel::Operation
+      #     result!
+      #
+      #     settings Struct.new(:say, :other)
+      #     settings_constructor ->(data) { settings.new(*data.values_at(*settings.members)) }
+      #
+      #     input none
+      #     output Hash
+      #     error none
+      #
+      #     def call(_)
+      #       settings.to_h
+      #     end
+      #   end
+      #
+      #   class Chain
+      #     include Teckel::Chain
+      #
+      #     default_settings!(a: { say: "Chain Default" })
+      #
+      #     step :a, MyOperation
+      #   end
+      #
+      #   # Using the chains default settings
+      #   result = Chain.call
+      #   result.success #=> {say: "Chain Default", other: nil}
+      #
+      #   # explicit settings passed via `with` will overwrite all defaults
+      #   result = Chain.with(a: { other: "What" }).call
+      #   result.success #=> {say: nil, other: "What"}
+      def default_settings!(settings) # :nodoc: The bang is for consistency with the Operation class
+        @config.for(:default_settings, settings)
+      end
+
+      # Getter for configured default settings
+      # @return [nil|#call] The callable constructor
+      def default_settings
+        @config.for(:default_settings)
+      end
+
+      REQUIRED_CONFIGS = %i[around runner result result_constructor].freeze
+
+      # @!visibility private
+      # @return [void]
+      def define!
+        raise MissingConfigError, "Cannot define Chain with no steps" if steps.empty?
+
+        REQUIRED_CONFIGS.each { |e| public_send(e) }
+        steps.each(&:finalize!)
+        nil
+      end
+
+      # Disallow any further changes to this Chain.
+      # @note This also calls +finalize!+ on all Operations defined as steps.
+      #
+      # @return [self] Frozen self
+      # @!visibility public
+      def finalize!
+        define!
+        steps.freeze
+        @config.freeze
+        self
+      end
+
+      # Produces a shallow copy of this chain.
+      # It's {around}, {runner} and {steps} will get +dup+'ed
+      #
+      # @return [self]
+      # @!visibility public
+      def dup
+        dup_config(super)
+      end
+
+      # Produces a clone of this chain.
+      # It's {around}, {runner} and {steps} will get +dup+'ed
+      #
+      # @return [self]
+      # @!visibility public
+      def clone
+        if frozen?
+          super
+        else
+          dup_config(super)
+        end
+      end
+
+      # @!visibility private
+      def inherited(subclass)
+        dup_config(subclass)
+      end
+
+      # @!visibility private
+      def self.extended(base)
+        base.instance_variable_set(:@config, Teckel::Config.new)
+      end
+
+      private
+
+      def dup_config(other_class)
+        new_config = @config.dup
+        new_config.replace(:steps) { steps.dup }
+
+        other_class.instance_variable_set(:@config, new_config)
+        other_class
+      end
+
+      def build_constructor(on, sym_or_proc)
+        if sym_or_proc.is_a?(Symbol) && on.respond_to?(sym_or_proc)
+          on.public_method(sym_or_proc)
+        elsif sym_or_proc.respond_to?(:call)
+          sym_or_proc
+        end
+      end
+    end
+  end
+end