trailblazer-activity 0.2.1 → 0.3.0

data/lib/trailblazer/activity/magnetic.rb

@@ -0,0 +1,47 @@
+module Trailblazer
+  class Activity
+    # all code related to the magnetic building of a circuit hash lives in this namespace.
+    module Magnetic
+      # PlusPole "radiates" a color that MinusPoles are attracted to.
+      #
+      # This datastructure is produced by the DSL and sits in an ADDS.
+      PlusPole = Struct.new(:output, :color) do
+        private :output
+
+        def signal
+          output.signal
+        end
+      end # PlusPole
+    end
+
+    class Process
+      def self.plan(options={}, &block)
+        Magnetic::Builder::Path.plan(options, &block)
+      end
+
+      def self.build(options={}, &block)
+        Magnetic::Builder::Path.build(options, &block)
+      end
+
+      def self.draft(options={}, &block) # TODO: remove me!
+        Magnetic::Builder::Path.draft(options, &block)
+      end
+    end
+
+  end
+end
+
+require "trailblazer/activity/magnetic/dsl"
+require "trailblazer/activity/magnetic/dsl/plus_poles"
+require "trailblazer/activity/magnetic/dsl/alterations"
+
+require "trailblazer/activity/schema/dependencies"
+
+require "trailblazer/activity/magnetic"
+require "trailblazer/activity/magnetic/builder"
+require "trailblazer/activity/magnetic/builder/block"
+require "trailblazer/activity/magnetic/builder/path"
+require "trailblazer/activity/magnetic/builder/railway"
+require "trailblazer/activity/magnetic/builder/fast_track" # TODO: move to Operation gem.
+
+require "trailblazer/activity/magnetic/generate"

data/lib/trailblazer/activity/magnetic/builder.rb

@@ -0,0 +1,161 @@
+require "trailblazer/activity/magnetic/finalizer"
+
+module Trailblazer
+  module Activity::Magnetic
+    def self.Builder(implementation, normalizer, builder_options={})
+      builder = implementation.new(normalizer, builder_options.freeze).freeze # e.g. Path.new(...)
+
+      return builder, implementation.InitialAdds(builder_options)
+    end
+
+    class Builder
+
+      def self.plan_for(builder, adds, &block)
+        adds += Block.new(builder).(&block) # returns ADDS
+      end
+
+      def self.build(options={}, &block)
+        adds = plan( options, &block )
+
+        Finalizer.(adds)
+      end
+
+      def initialize(normalizer, builder_options)
+        @normalizer, @builder_options = normalizer, builder_options
+      end
+
+      def self.merge(activity, merged)
+        merged = merged[2..-1] || []
+
+        activity + merged
+      end
+
+      module DSLMethods
+        #   Output( Left, :failure )
+        #   Output( :failure ) #=> Output::Semantic
+        def Output(signal, semantic=nil)
+          return DSL::Output::Semantic.new(signal) if semantic.nil?
+
+          Activity.Output(signal, semantic)
+        end
+
+        def End(name, semantic)
+          Activity.End(name, semantic)
+        end
+
+        def Path(track_color: "track_#{rand}", end_semantic: :success, **options)
+          options = options.merge(track_color: track_color, end_semantic: end_semantic)
+
+          # this block is called in DSL::ProcessTuples.
+          ->(block) { [ track_color, Builder::Path.plan( options, @normalizer, &block ) ] }
+        end
+      end
+
+      include DSLMethods
+
+      private
+
+      # Internal top-level entry point to add task(s) and connections.
+      def insert_element(impl, polarizations, task, options, &block)
+        adds, *returned_options = Builder.adds_for(polarizations, @normalizer, impl.keywords, task, options, &block)
+      end
+
+      # Options valid for all DSL calls with this Builder framework.
+      def self.generic_keywords
+        [ :id, :plus_poles, :magnetic_to, :adds ]
+      end
+
+      def self.sequence_keywords
+        [ :group, :before, :after, :replace, :delete ] # hard-wires Builder to Sequence/Alterations.
+      end
+
+      # Produce two hashes, one "local" options with DSL-specific options such as `:fast_track`,
+      # one with generic DSL options, for example tuples like `Right=>Output(:failure)`.
+      def self.normalize(options, local_keys)
+        local, foreign = {}, {}
+        options.each { |k,v| local_keys.include?(k) ? local[k] = v : foreign[k] = v }
+
+        return foreign, local
+      end
+
+      # @return Adds
+      # High level interface for DSL calls like ::task or ::step.
+      # TODO: RETURN ALL OPTIONS
+      def self.adds_for(polarizations, normalizer, keywords, task, options, &block)
+        task, local_options, options, sequence_options = normalize_options(normalizer, keywords, task, options)
+
+        initial_plus_poles = local_options[:plus_poles]
+        magnetic_to        = local_options[:magnetic_to]
+        adds               = local_options[:adds] || []
+
+        # go through all wiring options such as Output()=>:color.
+        polarizations_from_user_options, additional_adds = DSL::ProcessOptions.(local_options[:id], options, initial_plus_poles, &block)
+
+        result = adds(local_options[:id], task, initial_plus_poles, polarizations, polarizations_from_user_options, local_options, sequence_options, magnetic_to)
+
+        return result + adds + additional_adds, task, local_options, options, sequence_options
+      end
+
+      # @private
+      def self.normalize_options(normalizer, keywords, task, options)
+         # sort through the "original" user DSL options.
+        options, local_options    = normalize( options, generic_keywords+keywords ) # DISCUSS:
+        options, sequence_options = normalize( options, sequence_keywords )
+
+        task, local_options, options, sequence_options = normalizer.(task, local_options, options, sequence_options)
+
+        return task, local_options, options, sequence_options
+      end
+
+      # Low-level interface for DSL calls (e.g. Start, where "you know what you're doing")
+      # @private
+      def self.adds(id, task, initial_plus_poles, polarization, polarizations_from_user_options, options, sequence_options, magnetic_to = nil)
+        magnetic_to, plus_poles = apply_polarizations(
+          polarization + polarizations_from_user_options,
+          magnetic_to,
+          initial_plus_poles,
+          options
+        )
+
+        Add( id, task, magnetic_to, plus_poles,
+          options,         #{ fast_track: true },
+          sequence_options #{ group: :main }
+        )
+      end
+
+      # Called once per DSL method call, e.g. ::step.
+      #
+      # The idea is to chain a bunch of PlusPoles transformations (and magnetic_to "transformations")
+      # for each DSL call, and thus realize things like path+railway+fast_track
+      def self.apply_polarizations(polarizations, magnetic_to, plus_poles, options)
+        polarizations.inject([magnetic_to, plus_poles]) do |args, pol|
+          magnetic, plus_poles = pol.(*args, options)
+        end
+      end
+
+      def self.Add(id, task, magnetic_to, plus_poles, options, sequence_options)
+        [
+          [ :add, [id, [ magnetic_to, task, plus_poles.to_a ], sequence_options] ],
+        ]
+      end
+
+      class DefaultNormalizer
+        def initialize( **default_options )
+          raise "you didn't specify default :plus_poles" unless default_options[:plus_poles]
+
+          @default_options = default_options
+        end
+
+        # called for every ::task, ::step call etc to defaultize the `local_options`.
+        def call(task, local_options, options, sequence_options)
+          local_options = @default_options.merge(local_options) # here, we merge default :plus_poles.
+
+          return task, local_options, options, sequence_options
+        end
+      end
+
+    end # Builder
+  end
+end
+
+

data/lib/trailblazer/activity/magnetic/builder/block.rb

@@ -0,0 +1,37 @@
+module Trailblazer
+  module Activity::Magnetic
+    # Mutable DSL object.
+    #
+    # This is the only object mutated when building the ADDS, and it's only
+    # used when using block-syntax, such as
+    #   Path.plan do
+    #     # ..
+    #   end
+    class Builder::Block
+      def initialize(builder)
+        @builder = builder
+        @adds    = [] # mutable
+      end
+
+      # Evaluate user's block and return the new ADDS.
+      # Used in Builder::plan or in nested DSL calls.
+      def call(&block)
+        instance_exec(&block)
+        @adds
+      end
+
+      [:task, :step, :pass, :fail].each do |name| # create :step, :pass, :task, etc.
+        define_method(name) { |*args, &block| capture_adds(name, *args, &block) } # def step(..) => forward to builder, track ADDS
+      end
+
+      extend Forwardable
+      def_delegators :@builder, :Output, :Path, :End # TODO: make this official.
+
+      # #task, #step, etc. are called via the immutable builder.
+      def capture_adds(name, *args, &block)
+        adds, *returned_options = @builder.send(name, *args, &block)
+        @adds += adds
+      end
+    end
+  end
+end

data/lib/trailblazer/activity/magnetic/builder/fast_track.rb

@@ -0,0 +1,141 @@
+# TODO: move me to Operation.
+module Trailblazer
+  module Activity::Magnetic
+    class Builder
+
+      class FastTrack < Builder
+        def self.for(normalizer, builder_options={}) # Build the Builder.
+          Activity::Magnetic::Builder(
+            FastTrack,
+            normalizer,
+            { track_color: :success, end_semantic: :success, failure_color: :failure }.merge( builder_options )
+          )
+        end
+
+        def self.plan(options={}, normalizer=DefaultNormalizer.new(plus_poles: default_plus_poles), &block)
+          plan_for( *FastTrack.for(normalizer, options), &block )
+        end
+
+        def self.StepPolarizations(**options)
+          [
+            *Railway.StepPolarizations(options),
+            StepPolarization.new(options)
+          ]
+        end
+
+        def self.FailPolarizations(**options)
+          [
+            *Railway.FailPolarizations(options),
+            FailPolarization.new(options)
+          ]
+        end
+
+        def self.PassPolarizations(**options)
+          [
+            *Railway.PassPolarizations(options),
+            PassPolarization.new(options)
+          ]
+        end
+
+        # pass_fast: true simply means: color my :success Output with :pass_fast color
+        class StepPolarization < Railway::StepPolarization
+          def call(magnetic_to, plus_poles, options)
+            plus_poles = plus_poles.reconnect( :success   => :pass_fast ) if options[:pass_fast]
+            plus_poles = plus_poles.reconnect( :failure   => :fail_fast ) if options[:fail_fast]
+
+            # add fast track outputs if :fast_track
+            plus_poles = plus_poles.reverse_merge(
+              Activity.Output(FailFast, :fail_fast) => :fail_fast,
+              Activity.Output(PassFast, :pass_fast) => :pass_fast
+            ) if options[:fast_track]
+
+            [
+              magnetic_to,
+              plus_poles
+            ]
+          end
+        end
+
+        class FailPolarization < Railway::StepPolarization
+          def call(magnetic_to, plus_poles, options)
+            plus_poles = plus_poles.reconnect( :failure => :fail_fast, :success => :fail_fast ) if options[:fail_fast]
+            plus_poles = plus_poles.reverse_merge( Activity.Output(FailFast, :fail_fast) => :fail_fast, Activity.Output(PassFast, :pass_fast) => :pass_fast ) if options[:fast_track]
+
+            [
+              magnetic_to,
+              plus_poles
+            ]
+          end
+        end
+
+        class PassPolarization < Railway::StepPolarization
+          def call(magnetic_to, plus_poles, options)
+            plus_poles = plus_poles.reconnect( :success => :pass_fast, :failure => :pass_fast ) if options[:pass_fast]
+            plus_poles = plus_poles.reverse_merge( Activity.Output(FailFast, :fail_fast) => :fail_fast, Activity.Output(PassFast, :pass_fast) => :pass_fast ) if options[:fast_track]
+
+            [
+              magnetic_to,
+              plus_poles
+            ]
+          end
+        end
+
+        def self.default_plus_poles(*args)
+          Railway.default_plus_poles(*args)
+        end
+
+        def self.keywords
+          [:fail_fast, :pass_fast, :fast_track, :type, :override]
+        end
+
+
+        # Adds the End.fail_fast and End.pass_fast end to the Railway sequence.
+        def self.InitialAdds(pass_fast_end: Activity.End("pass_fast", :pass_fast), fail_fast_end: Activity.End("fail_fast", :fail_fast), **builder_options)
+          path_adds = Railway.InitialAdds(**builder_options)
+
+          ends =
+            adds(
+              "End.pass_fast", pass_fast_end,
+
+              {}, # plus_poles
+              Path::TaskPolarizations(builder_options.merge( type: :End )),
+              [],
+
+              {},
+              { group: :end },
+              [:pass_fast]
+            )+
+            adds(
+              "End.fail_fast", fail_fast_end,
+
+              {}, # plus_poles
+              Path::TaskPolarizations(builder_options.merge( type: :End )),
+              [],
+
+              {},
+              { group: :end },
+              [:fail_fast]
+            )
+
+          path_adds + ends
+        end
+
+        # Direction signals.
+        FailFast = Class.new(Activity::Signal)
+        PassFast = Class.new(Activity::Signal)
+
+        def step(task, options={}, &block)
+          insert_element( FastTrack, FastTrack.StepPolarizations(@builder_options), task, options, &block )
+        end
+
+        def fail(task, options={}, &block)
+          insert_element( FastTrack, FastTrack.FailPolarizations(@builder_options), task, options, &block )
+        end
+
+        def pass(task, options={}, &block)
+          insert_element( FastTrack, FastTrack.PassPolarizations(@builder_options), task, options, &block )
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/activity/magnetic/builder/path.rb

@@ -0,0 +1,98 @@
+module Trailblazer
+  module Activity::Magnetic
+    class Builder
+
+      class Path < Builder
+          # strategy_options:
+          #   :track_color
+          #   :end_semantic
+        def self.for(normalizer, builder_options={}) # Build the Builder.
+          Activity::Magnetic::Builder(
+            Path,
+            normalizer,
+            { track_color: :success, end_semantic: :success }.merge( builder_options )
+          )
+        end
+
+        def self.plan(options={}, normalizer=DefaultNormalizer.new(plus_poles: default_plus_poles), &block)
+          plan_for( *Path.for(normalizer, options), &block )
+        end
+
+
+        def self.keywords
+          [:type]
+        end
+
+        def task(task, options={}, &block)
+          polarizations = Path.TaskPolarizations( @builder_options.merge(type: options[:type]) ) # DISCUSS: handle :type here? Really?
+
+          insert_element( Path, polarizations, task, options, &block )
+        end
+
+
+        def self.default_plus_poles
+          DSL::PlusPoles.new.merge(
+            Activity.Output( Activity::Right, :success ) => nil
+          ).freeze
+        end
+
+        # @return [Adds] list of Adds instances that can be chained or added to an existing sequence.
+        def self.InitialAdds(track_color:raise, end_semantic:raise, default_plus_poles: self.default_plus_poles, track_end: Activity.End(track_color, end_semantic), **o)
+
+          builder_options={ track_color: track_color, end_semantic: end_semantic }
+
+          start_adds = adds(
+            "Start.default", Activity::Start.new(:default),
+
+            default_plus_poles,
+            TaskPolarizations(builder_options),
+            [],
+
+            {}, { group: :start },
+            [] # magnetic_to
+          )
+
+          end_adds = adds(
+            "End.#{track_color}", track_end,
+
+            {}, # plus_poles
+            TaskPolarizations(builder_options.merge( type: :End )),
+            [],
+
+            {}, { group: :end }
+          )
+
+          start_adds + end_adds
+        end
+
+        def self.TaskPolarizations(track_color:raise, type: :task, **o)
+          return [EndPolarization.new( track_color: track_color )] if type == :End # DISCUSS: should this dispatch be here?
+
+          [TaskPolarization.new( track_color: track_color )]
+        end
+
+        class TaskPolarization
+          def initialize( track_color:raise )
+            @track_color = track_color
+          end
+
+          def call(magnetic_to, plus_poles, options)
+            [
+              magnetic_to || [@track_color],
+              plus_poles.reconnect( :success => @track_color )
+            ]
+          end
+        end # TaskPolarization
+
+        class EndPolarization < TaskPolarization
+          def call(magnetic_to, plus_poles, options)
+            [
+              magnetic_to || [@track_color],
+              {}
+            ]
+          end
+        end # EndPolarization
+      end # Path
+    end # Builder
+  end
+end