trailblazer-activity 0.3.2 → 0.4.o

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 45961f74078de84b48e1d65403b6924e82fef026
-  data.tar.gz: 29aab14192b6de4e418ac9668b3aa306c785420f
+SHA256:
+  metadata.gz: 7eb2fd05fd42b86db598839e4903e7f81cd44f43f435625a2907c689df522675
+  data.tar.gz: f83b35f3c13b44f11f36eec569fbcb008f5681a935ce078316648dd7036a7e88
 SHA512:
-  metadata.gz: 0e5ec16c9bbf0c3f7ce34bf2b80d544cc51dd750c21a5f4516413b5ce83121642fa8ad5cf47cd6790168f479a57adcc0252da9c0beafdc82ce0802e1ea213965
-  data.tar.gz: e38ad33a55650947db2df5aa87b785d78d6c1f92603afcfe26352dfb36f92454a017e5ea08148249afb1524b4fa5464ff1c4f48bc01f0947700619d358f767b6
+  metadata.gz: f1b5afb1f62768f177a77dece7954d0251df6f2568373e134aa54aa4535998bba270795ffc200b00bd6b5cb892237452bf0799f492d35cc8ad43fe0e13f83714
+  data.tar.gz: 0e6c7a8abb6b7e5db35ac1a154389eed2c6462e6fce1fcd8d502edf4cfd8484037a1c769b096add34a952b74ca1eac4630861d245c4c955d5d8528f343b6d0c7

data/.travis.yml

@@ -1,13 +1,14 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.0
+  # - 2.0
   - 2.1
   - 2.2
   - 2.3.3
-  - 2.4.0
+  - 2.4.1
+  - 2.5.0
 matrix:
   include:
-  - rvm: jruby-9.1.13.0
+  - rvm: jruby-9.1.15.0
     env: JRUBY_OPTS="--profile.api"
 before_install: gem install bundler

data/CHANGES.md

@@ -1,3 +1,7 @@
+# 0.4.0
+
+* We now use the "Module Subclass" pattern, and activities aren't classes anymore but modules.
+
 # 0.3.2
 
 * In the `TaskWrap`, rename `:result_direction` to `:return_signal` and `:result_args` to `:return_args`,

data/lib/trailblazer/activity.rb

@@ -1,177 +1,119 @@
-require "trailblazer/circuit"
+require "trailblazer/activity/version"
 
 module Trailblazer
-  class Activity
-    module Interface
-      def decompose # TODO: test me
-        @process.instance_variable_get(:@circuit).to_fields
-      end
-
-      def debug # TODO: TEST ME
-        @debug
-      end
-    end
-
-    extend Interface
-
-    require "trailblazer/activity/version"
-    require "trailblazer/activity/structures"
-
-    require "trailblazer/activity/subprocess"
-
-    require "trailblazer/activity/wrap"
-    require "trailblazer/wrap/call_task"
-    require "trailblazer/wrap/trace"
-    require "trailblazer/wrap/runner"
-
-    require "trailblazer/activity/trace"
-    require "trailblazer/activity/present"
-
+  def self.Activity(implementation=Activity::Path, options={})
+    Activity.new(implementation, state)
+  end
 
-    require "trailblazer/activity/magnetic" # the "magnetic" DSL
-    require "trailblazer/activity/schema/sequence"
+  class Activity < Module
+    attr_reader :initial_state
 
-    require "trailblazer/activity/process"
-    require "trailblazer/activity/introspection"
+    def initialize(implementation, options)
+      builder, adds, circuit, outputs, options = BuildState.build_state_for( implementation.config, options)
 
-    require "trailblazer/activity/heritage"
+      @initial_state = State::Config.build(
+        builder: builder,
+        options: options,
+        adds:    adds,
+        circuit: circuit,
+        outputs: outputs,
+      )
 
-    def self.call(args, circuit_options={})
-      @process.( args, circuit_options )
+      include *options[:extend] # include the DSL methods.
+      include PublicAPI
     end
 
-    #- modelling
-
-    # @private
-    # DISCUSS: #each instead?
-    # FIXME: move to Introspection
-    def self.find(&block)
-      @process.instance_variable_get(:@circuit).instance_variable_get(:@map).find(&block)
-    end
-
-    def self.outputs
-      @outputs
+    # Injects the initial configuration into the module defining a new activity.
+    def extended(extended)
+      super
+      extended.instance_variable_set(:@state, initial_state)
     end
 
-    #- DSL part
 
-    def self.build(&block)
-      Class.new(self, &block)
+    module Inspect
+      def inspect
+        "#<Trailblazer::Activity: {#{name || self[:options][:name]}}>"
+      end
     end
 
-    private
 
-    def self.inherited(subclass)
-      super
-      subclass.initialize!(*subclass.config)
-      heritage.(subclass)
-    end
-
-    def self.initialize!(builder_class, normalizer)
-      initialize_activity_dsl!(builder_class, normalizer)
-      recompile_process!
-    end
+    require "trailblazer/activity/dsl/helper"
+    # Helpers such as Path, Output, End to be included into {Activity}.
+    module DSLHelper
+      extend Forwardable
+      def_delegators :@builder, :Path
+      def_delegators DSL::Helper, :Output, :End
 
-    # builder is stateless, it's up to you to save @adds somewhere.
-    def self.initialize_activity_dsl!(builder_class, normalizer)
-      @builder, @adds = builder_class.for( normalizer ) # e.g. Path.for(...) which creates a Builder::Path instance.
-      @debug          = {} # only @adds and @debug are mutable
-    end
-
-    def self.recompile_process!
-      @process, @outputs = Recompile.( @adds )
+      def Path(*args, &block)
+        self[:builder].Path(*args, &block)
+      end
     end
 
-    def self.config # FIXME: the normalizer is the same we have in Builder::plan.
-      return Magnetic::Builder::Path, Magnetic::Builder::DefaultNormalizer.new(plus_poles: Magnetic::Builder::Path.default_plus_poles)
-    end
+    module Accessor
+      def []=(*args)
+        @state = State::Config.send(:[]=, @state, *args)
+      end
 
-    # DSL part
-
-    # DISCUSS: make this functions and don't include?
-    module DSL
-
-      # Create a new method (e.g. Activity::step) that delegates to its builder, recompiles
-      # the process, etc. Method comes in a module so it can be overridden via modules.
-      #
-      # This approach assumes you maintain a @adds and a @debug instance variable. and #heritage
-      def self.def_dsl!(_name)
-        Module.new do
-          define_method(_name) do |*args, &block|
-            _task(_name, *args, &block)  # TODO: similar to Block.
-          end
-        end
+      def [](*args)
+        State::Config[@state, *args]
       end
+    end
 
-      private
+    # FIXME: still to be decided
+    # By including those modules, we create instance methods.
+    # Later, this module is `extended` in Path, Railway and FastTrack, and
+    # imports the DSL methods as class methods.
+    module PublicAPI
+      include Accessor
 
-      def _task(name, *args, &block)
-        heritage.record(name, *args, &block)
+    require "trailblazer/activity/dsl/add_task"
+      include DSL::AddTask
 
-        adds, *returned_options = @builder.send(name, *args, &block)
+    require "trailblazer/activity/implementation/interface"
+      include Activity::Interface # DISCUSS
 
-        @adds += adds
-        @adds.freeze
+      include DSLHelper # DISCUSS
 
-        recompile_process!
+      include Activity::Inspect # DISCUSS
 
-        add_introspection!(adds, *returned_options)
+    require "trailblazer/activity/magnetic/merge"
+      include Magnetic::Merge # Activity#merge!
 
-        return adds, returned_options
-      end
+      def call(args, argumenter: [], **circuit_options) # DISCUSS: the argumenter logic might be moved out.
+        _, args, circuit_options = argumenter.inject( [self, args, circuit_options] ) { |memo, argumenter| argumenter.(*memo) }
 
-      def add_introspection!(adds, task, local_options, *)
-        @debug[task] = { id: local_options[:id] }.freeze
+        self[:circuit].( args, circuit_options.merge(argumenter: argumenter) )
       end
     end
+  end # Activity
+end
 
-    # delegate as much as possible to Builder
-    # let us process options and e.g. do :id
-    class << self
-      extend Forwardable # TODO: test those helpers
-      def_delegators :@builder, :Path#, :task
-    end
-
-    extend DSL                  # _task, :add_introspection
-    extend DSL.def_dsl!(:task)  # define Activity::task.
-
-    extend Heritage::Accessor
+require "trailblazer/circuit"
+require "trailblazer/activity/structures"
+require "trailblazer/activity/config"
 
+require "trailblazer/activity/implementation/build_state"
+require "trailblazer/activity/implementation/interface"
+require "trailblazer/activity/implementation/path"
+require "trailblazer/activity/implementation/railway"
+require "trailblazer/activity/implementation/fast_track"
 
-    # MOVE ME TO ADDS
-    module Recompile
-      # Recompile the process and outputs from the {ADDS} instance that collects circuit tasks and connections.
-      def self.call(adds)
-        process, end_events = Magnetic::Builder::Finalizer.(adds)
-        outputs             = recompile_outputs(end_events)
+require "trailblazer/activity/task_wrap"
+require "trailblazer/activity/task_wrap/call_task"
+require "trailblazer/activity/task_wrap/trace"
+require "trailblazer/activity/task_wrap/runner"
+require "trailblazer/activity/task_wrap/merge"
 
-        return process, outputs
-      end
+require "trailblazer/activity/trace"
+require "trailblazer/activity/present"
 
-      private
+require "trailblazer/activity/introspect"
 
-      def self.recompile_outputs(end_events)
-        ary = end_events.collect do |evt|
-          [
-            semantic = evt.instance_variable_get(:@options)[:semantic], # DISCUSS: better API here?
-            Activity::Output(evt, semantic)
-          ]
-        end
-
-        ::Hash[ ary ]
-      end
-    end
+# require "trailblazer/activity/heritage"
+require "trailblazer/activity/subprocess"
 
-    # TODO: hm
-    class Railway < Activity
-      def self.config # FIXME: the normalizer is the same we have in Builder::plan.
-        return Magnetic::Builder::Railway, Magnetic::Builder::DefaultNormalizer.new(plus_poles: Magnetic::Builder::Railway.default_plus_poles)
-      end
+require "trailblazer/activity/state"
+require "trailblazer/activity/magnetic" # the "magnetic" DSL
+require "trailblazer/activity/schema/sequence"
 
-      extend DSL
-      extend DSL.def_dsl!(:step)
-      extend DSL.def_dsl!(:fail)
-      extend DSL.def_dsl!(:pass)
-    end
-  end
-end
+require "trailblazer/activity/magnetic/builder/normalizer" # DISCUSS: name and location are odd. This one uses Activity ;)

data/lib/trailblazer/activity/config.rb

@@ -0,0 +1,37 @@
+module Trailblazer
+  module Activity::State
+    # Compile-time
+    #
+    # DISCUSS: we could replace parts with Hamster::Hash.
+    class Config
+      def self.build(variables={})
+        Hash[ variables.collect { |k,v| [k, v.freeze] } ].freeze
+      end
+
+      def self.[]=(state, *args)
+        if args.size == 2
+          key, value = *args
+
+          state = state.merge(key => value)
+        else
+          directive, key, value = *args
+
+          state = state.merge( directive => {}.freeze ) unless state.key?(directive)
+
+          directive_hash = state[directive].merge(key => value)
+          state = state.merge( directive => directive_hash.freeze )
+        end
+
+        state
+      end
+
+      def self.[](state, *args)
+        directive, key = *args
+
+        return state[directive] if args.size == 1
+        return state[directive][key] if state.key?(directive)
+        nil
+      end
+    end
+  end
+end

data/lib/trailblazer/activity/dsl/add_task.rb

@@ -0,0 +1,22 @@
+class Trailblazer::Activity < Module
+  module DSL
+    module AddTask
+      def add_task!(name, task, options, &block)
+        # The beautiful thing about State.add is it doesn't mutate anything.
+        # We're changing state here, on the outside, by overriding the ivars.
+        # That in turn means, the only mutated entity is this module.
+
+        _builder, adds, circuit, outputs, options = State.add( self[:builder], self[:adds], name, task, options, &block ) # this could be an extension itself.
+
+        self[:adds]    = adds
+        self[:circuit] = circuit
+        self[:outputs] = outputs
+
+        task, local_options = options
+
+        # {Extension API} call all extensions.
+        local_options[:extension].collect { |ext| ext.(self, *options) } if local_options[:extension]
+      end
+    end
+  end
+end

data/lib/trailblazer/activity/dsl/helper.rb

@@ -0,0 +1,49 @@
+module Trailblazer
+  module Activity::DSL
+    # Create a new method (e.g. Activity::step) that delegates to its builder, recompiles
+    # the circuit, etc. Method comes in a module so it can be overridden via modules.
+    #
+    # This approach assumes you maintain a {#add_task!} method.
+    def self.def_dsl(_name)
+      Module.new do
+        define_method(_name) do |task, options={}, &block|
+          builder, adds, circuit, outputs, options = add_task!(_name, task, options, &block)  # TODO: similar to Block.
+        end
+      end
+    end
+
+    # Shortcut functions for the DSL. These have no state.
+    module Helper
+      module_function
+
+      #   Output( Left, :failure )
+      #   Output( :failure ) #=> Output::Semantic
+      def Output(signal, semantic=nil)
+        return Activity::Magnetic::DSL::Output::Semantic.new(signal) if semantic.nil?
+
+        Activity.Output(signal, semantic)
+      end
+
+      def End(name, semantic)
+        Activity.End(name, semantic)
+      end
+
+      def Path(normalizer, track_color: "track_#{rand}", end_semantic: :success, **options)
+        options    = options.merge(track_color: track_color, end_semantic: end_semantic)
+
+        # Build an anonymous class which will be where the block is evaluated in.
+        # We use the same normalizer here, so DSL calls in the inner block have the same behavior.
+        path = Module.new do
+          extend Activity::Path( options.merge( normalizer: normalizer ) )
+        end
+
+        # this block is called in DSL::ProcessTuples. This could be improved somehow.
+        ->(block) {
+          path.instance_exec(&block)
+
+          [ track_color, path ]
+        }
+      end
+    end
+  end
+end

data/lib/trailblazer/activity/implementation/build_state.rb

@@ -0,0 +1,31 @@
+class Trailblazer::Activity < Module
+  module BuildState
+    # Compute all objects that need to be passed into the new Activity module.
+    # 1. Build the normalizer (unless passed with :normalizer)
+    # 2. Build the builder (in State)
+    # 3. Let State compute all state variables (that implies recompiling the Process)
+    #
+    # @return [Builder, Adds, Process, Outputs, remaining options]
+    # @api private
+    def self.build_state_for(default_options, options)
+      options                                  = default_options.merge(options) # TODO: use Variables::Merge() here.
+      normalizer, options                      = build_normalizer(options)
+      builder, adds, circuit, outputs, options = build_state(normalizer, options)
+    end
+
+    # Builds the normalizer (to process options in DSL calls) unless {:normalizer} is already set.
+    #
+    # @api private
+    def self.build_normalizer(normalizer_class:, normalizer: false, **options)
+      normalizer, options = normalizer_class.build( options ) unless normalizer
+
+      return normalizer, options
+    end
+
+    def self.build_state(normalizer, builder_class:, builder_options: {}, **options)
+      builder, adds, circuit, outputs = State.build(builder_class, normalizer, options.merge(builder_options))
+
+      return builder, adds, circuit, outputs, options
+    end
+  end
+end

data/lib/trailblazer/activity/implementation/fast_track.rb

@@ -0,0 +1,14 @@
+class Trailblazer::Activity < Module
+  def self.FastTrack(options={})
+    FastTrack.new(FastTrack, options)
+  end
+
+  # Implementation module that can be passed to `Activity[]`.
+  class FastTrack < Trailblazer::Activity
+    def self.config
+      Railway.config.merge(
+        builder_class:  Magnetic::Builder::FastTrack,
+      )
+    end
+  end
+end