railway_operation 0.1.0

data/lib/railway_operation/operator.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'deep_clone'
+
+module RailwayOperation
+  module Operator
+    DEFAULT_STRATEGY = Strategy::DEFAULT
+
+    # The DynamicRun allows the module which includes it to have a method
+    # with that is run_<something>.
+    #
+    # ex: run_variation1, run_something, run_my_operation_name
+    module DynamicRun
+      CAPTURE_OPERATION_NAME = /run_*(?<operation>\w*)/
+
+      def respond_to_missing?(method, _include_private = false)
+        method.match(CAPTURE_OPERATION_NAME)
+      end
+
+      def method_missing(method, *args, &block)
+        return super unless method.match?(CAPTURE_OPERATION_NAME)
+
+        operation = method.match(CAPTURE_OPERATION_NAME)[:operation]
+        run(args[0], operation: operation, **(args[1] || {}))
+      end
+    end
+
+    # The operator class method allows classes which include this module
+    # to delegate actions to the default operation of the @operations
+    # array.
+    #
+    # The default operation is a normal RailwayOperation::Operation classes
+    # however it is used to store step declarations as well as other operation
+    # attributes such as track_alias, fails_step, etc. If other operations of
+    # the class do not declare values for these attributes, the values
+    # assigned to the default operation is used.
+    module ClassMethods
+      include DynamicRun
+
+      def operation(operation_or_name = :default)
+        @operations ||= {}
+
+        name = Operation.format_name(operation_or_name)
+        op = @operations[name] ||= Operation.new(operation_or_name)
+
+        # See operation/nested_operation_spec.rb for details for block syntax
+
+        block_given? ? yield(op) : op
+      end
+
+      def run(argument, operation: :default, **opts)
+        new.run(argument, operation: operation, **opts)
+      end
+    end
+
+    # The RailwayOperation::Operator instance methods exposes a single
+    # method - RailwayOperation::Operator#run
+    #
+    # This method is intended to run thpe default operation. Although it's
+    # possible to invoke ohter operations of the class the method missing
+    # approach is preffered (ie run_<operation_name>)
+    module InstanceMethods
+      include DynamicRun
+      include Surround
+
+      def run(argument, operation: :default, track_identifier: 1, step_index: 0, **info)
+        op = self.class.operation(operation)
+
+        wrap(*op.operation_surrounds) do
+          _run(
+            argument,
+            Info.new(operation: op, **info),
+            track_identifier: op.track_identifier(track_identifier),
+            step_index: step_index
+          )
+        end
+      end
+
+      def run_step(argument, operation: :default, track_identifier:, step_index:, **info)
+        op = self.class.operation(operation)
+
+        new_info = Info.new(operation: op, **info)
+        new_info.execution.add_step(
+          argument: argument,
+          track_identifier: track_identifier,
+          step_index: step_index
+        )
+
+        _run_step(argument, new_info)
+      end
+
+      private
+
+      def _run_step(argument, info)
+        step = info.execution.last
+
+        step_definition = info.operation[step.track_identifier, step.step_index]
+        unless step_definition
+          step.noop!
+          return [argument, info]
+        end
+
+        step.start!
+
+        surrounds = info.operation.step_surrounds[step.track_identifier] + info.operation.step_surrounds['*']
+        wrap_arguments = [DeepClone.clone(argument), info]
+
+        step[:method] = step_definition
+        step[:noop] = false
+
+        step[:argument] = wrap(*surrounds, arguments: wrap_arguments) do
+          case step_definition
+          when Symbol
+            # add_step 1, :method
+            public_send(step_definition, *wrap_arguments)
+          when Array
+            # add_step 1, [MyClass, :method]
+            step_definition[0].send(step_definition[1], *wrap_arguments)
+          else
+            # add_step 1, ->(argument, info) { ... }
+            step_definition.call(*wrap_arguments)
+          end
+        end
+
+        step.end!
+
+        [step[:argument], info]
+      end
+
+      def _run(argument, info, track_identifier:, step_index:)
+        return [argument, info] if step_index > info.operation.last_step_index
+
+        info.execution.add_step(
+          argument: argument,
+          track_identifier: track_identifier,
+          step_index: step_index
+        )
+
+        stepper_fn = info.operation.stepper_function || DEFAULT_STRATEGY
+
+        vector = Stepper.step(stepper_fn, info) do
+          _run_step(argument, info)
+        end
+
+        _run(
+          vector[:argument].(info),
+          info,
+          track_identifier: vector[:track_identifier].(info),
+          step_index: vector[:step_index].(info)
+        )
+      end
+    end
+  end
+end

data/lib/railway_operation/stepper.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module RailwayOperation
+  # This class is responsible for calculating the vector of the next step
+  # during an operation execution
+  class Stepper
+    module Argument
+      DEFAULT = ->(execution:, **) { execution.last[:argument] }
+      INITIAL = ->(execution:, **) { execution.first[:argument] }
+      PREVIOUS = ->(execution:, **) { execution[-2][:argument] }
+    end
+
+    module TrackIdentifier
+      DEFAULT = ->(execution:, **) { execution.last.track_identifier }
+      INITIAL = ->(operation:, **) { operation.initial_track }
+      NOOP = ->(operation:, **) { operation.noop_track }
+    end
+
+    module StepIndex
+      DEFAULT = ->(execution:, **) { execution.last.step_index + 1 }
+      INITIAL = ->(_) { 0 }
+      CURRENT = ->(execution:, **) { execution.last.step_index }
+    end
+
+    def vector
+      @vector ||= {
+        argument: Argument::DEFAULT,
+        step_index: StepIndex::DEFAULT,
+        track_identifier: TrackIdentifier::DEFAULT
+      }
+    end
+
+    def [](key)
+      vector[key]
+    end
+
+    def self.step(*args, &block)
+      new.step(*args, &block)
+    end
+
+    def step(stepper_function, info, &step_executor)
+      stepper_function.call(self, info, &step_executor)
+      self
+    end
+
+    # Manipulators
+
+    def continue
+      vector
+    end
+
+    def switch_to(specified_track)
+      vector[:track_identifier] = lambda do |execution:, operation:, **|
+        begin
+          track = case specified_track
+                  when Proc
+                    specified_track.call(operation, execution.last.track_identifier)
+                  else
+                    specified_track
+                  end
+
+          operation.track_index(track) # ensures that track index is found in the operation
+          track
+        rescue Operation::NonExistentTrack
+          raise "Invalid stepper_function specification for '#{operation.name}'"\
+            "operation: invalid `switch_to(#{track})`"
+        end
+      end
+    end
+
+    def retry_step
+      vector.merge!(
+        argument: Argument::PREVIOUS,
+        track_identifier: TrackIdentifier::DEFAULT
+      )
+
+      self
+    end
+
+    def restart_operation
+      vector.merge!(
+        argument: Argument::INITIAL,
+        track_identifier: TrackIdentifier::INITIAL
+      )
+
+      self
+    end
+
+    def halt_operation
+      vector.merge!(
+        argument: Argument::DEFAULT,
+        track_identifier: TrackIdentifier::NOOP
+      )
+
+      self
+    end
+
+    def fail_operation
+      vector.merge!(
+        argument: Argument::INITIAL,
+        track_identifier: TrackIdentifier::NOOP
+      )
+
+      self
+    end
+
+    def successor_track
+      lambda do |operation, current_track|
+        operation.successor_track(current_track)
+      end
+    end
+
+    def raise_error(e, info)
+      info.execution.last_step[:succeeded] = false
+      step_index = info.execution.length - 1
+      track_identifier = info.execution.last_step[:track_identifier]
+
+      message = "The operation was aborted because `#{e.class}' "\
+        "was raised on track #{track_identifier}, step #{step_index} of the operation."\
+        "\n\n#{info.display}\n\n"
+
+      raise e, message, e.backtrace
+    end
+  end
+end

data/lib/railway_operation/steps_array.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RailwayOperation
+  # Ensures that the array containing surrounds are of valid type
+  class StepsArray < Generic::TypedArray
+    def initialize(*args, **options)
+      types = [Symbol, Proc, String, Array]
+
+      super(
+        *args,
+        ensure_type_is: types,
+        error_message: 'Invalid operation surround declaration, must' \
+          "be of type #{types}",
+        **options
+      )
+    end
+  end
+end

data/lib/railway_operation/strategy.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RailwayOperation
+  class Strategy
+    DEFAULT = lambda do |stepper, info, &step|
+      begin
+        _result, new_info = step.call
+
+        if new_info.execution.last.failed?
+          stepper.fail_operation
+        end
+
+        stepper.continue
+      rescue StandardError => e
+        stepper.raise_error(e, new_info || info)
+      end
+    end
+
+    def self.standard
+      tracks = [:normal, :error_track, :fail_track]
+
+      stepper_fn = Strategy.norm_exceptional(
+        norm: {
+          normal: ->(execution) { !execution.errored? },
+          error_track: ->(execution) { execution.errored? },
+          fail_track: ->(execution) { execution.failed? }
+        }
+      )
+
+      [tracks, stepper_fn]
+    end
+
+    def self.norm_exceptional(norm: {}, exceptional: {})
+      lambda do |stepper, _, &step|
+        begin
+          _, new_info = step.call
+
+          track_switch = norm.detect do |_, predicate|
+            predicate.call(new_info.execution)
+          end.first
+
+          stepper.switch_to(track_switch) if track_switch
+          stepper.continue
+        rescue StandardError => e
+          track_switch = exceptional.detect do |_, predicate|
+            predicate.call(e)
+          end.first
+
+          stepper.raise_error(e, new_info || info) unless track_switch
+          stepper.switch_to(track_switch).continue
+        end
+      end
+    end
+  end
+end

data/lib/railway_operation/surround.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RailwayOperation
+  module Surround
+    def wrap(*surrounds, arguments: [], &body)
+      @body = body
+      @arguments = arguments
+
+      execute(surrounds)
+    end
+
+    private
+
+    def execute(surrounds)
+      surround, *rest = surrounds
+      result = nil
+
+      send_surround(surround, *@arguments) do
+        result = if rest.empty?
+                   @body.call
+                 else
+                   execute(rest)
+                 end
+      end
+
+      result
+    end
+
+    def send_surround(surround, *args)
+      case surround
+      when Symbol # wrap(with: :my_method)
+        send(surround, *args) { yield }
+      when Array # wrap(with: [MyClass, :method])
+        surround[0].send(surround[1], *args) { yield }
+      when Proc # wrap(with: -> { ... })
+        surround.call(-> { yield }, *args)
+      else # no wrap
+        yield(*args)
+      end
+    end
+  end
+end

data/lib/railway_operation/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailwayOperation
+  VERSION = '0.1.0'
+end

data/railway_operation.gemspec

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'railway_operation/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'railway_operation'
+  spec.version       = RailwayOperation::VERSION
+  spec.authors       = ['Felix Flores']
+  spec.email         = ['felixflores@gmail.com']
+
+  spec.summary       = 'This is a an implementation of the railway ' \
+                       'oriented programming pattern in ruby.'
+
+  spec.description   = 'This gem allows you to declare an execution ' \
+                       'tree for executing a series of methods and commands.'
+
+  spec.homepage      = 'https://github.com/felixflores/railway_operation/'
+  spec.license       = 'MIT'
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set
+  # the 'allowed_push_host' to allow pushing to a single host or delete
+  # this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+  else
+    raise 'RubyGems 2.0 or newer is required to protect against ' \
+          'public gem pushes.'
+  end
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'ruby_deep_clone'
+  spec.add_runtime_dependency 'terminal-table'
+
+  spec.add_development_dependency 'bundler', '~> 1.14'
+  spec.add_development_dependency 'pry-byebug'
+  spec.add_development_dependency 'pry-doc'
+  spec.add_development_dependency 'pry-rescue'
+  spec.add_development_dependency 'pry-clipboard'
+  spec.add_development_dependency 'pry-stack_explorer'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'simplecov'
+end