symbiont-ruby 0.0.0 → 0.1.0

data/lib/symbiont/executor.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Symbiont
+  # Mediator service object that controls the logic of creating triggers and calling them.
+  # Acts as a factory for trigerrs and a mediator for the proc invocation by them.
+  #
+  # @api public
+  # @since 0.1.0
+  module Executor
+    class << self
+      # Starts execution of a proc object in the context of the passed object with the selected
+      # direction of method dispatching. Delegates execution to a public trigger.
+      #
+      # @param required_context [Object]
+      # @param context_direction [Array<Symbol>]
+      # @param closure [Proc]
+      # @return void
+      #
+      # @see Symbiont::Trigger#__evaluate__
+      #
+      # @api public
+      # @since 0.1.0
+      def evaluate(required_context, context_direction = Trigger::IOK, &closure)
+        public_trigger(required_context, context_direction, &closure).__evaluate__
+      end
+
+      # Starts execution of a proc object in the context of the passed object with the selected
+      # direction of method dispatching. Delegates execution to a private trigger.
+      #
+      # @param required_context [Object]
+      # @param context_direction [Array<Symbol>]
+      # @param closure [Proc]
+      # @return void
+      #
+      # @see Symbiont::Trigger#__evaluate__
+      #
+      # @api public
+      # @since 0.1.0
+      def evaluate_private(required_context, context_direction = Trigger::IOK, &closure)
+        private_trigger(required_context, context_direction, &closure).__evaluate__
+      end
+
+      # Factory method that instantiates a public trigger with the desired execution context,
+      # the direction of method dispatching and the closure that needs to be performed.
+      #
+      # @param context_direction [Array<Symbol>]
+      # @param closure [Proc]
+      # @return [Symbiont::PublicTrigger]
+      #
+      # @see Symbiont::PublicTrigger
+      # @see Symbiont::Trigger
+      #
+      # @api public
+      # @since 0.1.0
+      def public_trigger(required_context, context_direction = Trigger::IOK, &closure)
+        PublicTrigger.new(required_context, closure, context_direction)
+      end
+
+      # Factory method that instantiates a private trigger with the desired execution context,
+      # the direction of method dispatching and the closure that needs to be performed.
+      #
+      # @param required_context [Any]
+      # @param context_direction [Array<Symbol>]
+      # @param closure [Proc]
+      # @return [Symbiont::PrivateTrigger]
+      #
+      # @see Symbiont::PrivateTrigger
+      # @see Symbiont::Trigger
+      #
+      # @api public
+      # @since 0.1.0
+      def private_trigger(required_context, context_direction = Trigger::IOK, &closure)
+        PrivateTrigger.new(required_context, closure, context_direction)
+      end
+
+      # Gets the method object taken from the context that can respond to it.
+      # Considers only public methods.
+      #
+      # @param method_name [Symbol,String]
+      # @param required_context [Any]
+      # @param context_direction [Array<Symbol>]
+      # @param closure [Proc]
+      # @return [Method]
+      #
+      # @see Symbiont::Trigger#method
+      #
+      # @api public
+      # @since 0.1.0
+      def public_method(method_name, required_context, context_direction = Trigger::IOK, &closure)
+        public_trigger(required_context, context_direction, &closure).method(method_name)
+      end
+
+      # Gets the method object taken from the context that can respond to it.
+      # Considers private methods and public methods.
+      #
+      # @param method_name [Symbol,String]
+      # @param required_context [Any]
+      # @param context_direction [Array<Symbol>]
+      # @param closure [Proc]
+      # @return [Method]
+      #
+      # @see Symbiont::Trigger#method
+      #
+      # @api public
+      # @since 0.1.0
+      def private_method(method_name, required_context, context_direction = Trigger::IOK, &closure)
+        private_trigger(required_context, context_direction, &closure).method(method_name)
+      end
+    end
+  end
+end

data/lib/symbiont/private_trigger.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Symbiont
+  # A trigger that considers both public and private methods of executable contexts
+  # during method dispatching.
+  #
+  # @api private
+  # @since 0.1.0
+  class PrivateTrigger < Trigger
+    # @param method_name [String,Symbol]
+    # @option include_private [Boolean]
+    # @raise NoMethodError
+    # @return [Objcet]
+    #
+    # @see Symbiont::Trigger#__actual_context__
+    #
+    # @since 0.1.0
+    def __actual_context__(method_name)
+      __directed_contexts__.find do |context|
+        context.respond_to?(method_name, true)
+      end || super
+    end
+  end
+end

data/lib/symbiont/public_trigger.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Symbiont
+  # A trigger that considers only public methods of executable contexts
+  # during method dispatching.
+  #
+  # @api private
+  # @since 0.1.0
+  class PublicTrigger < Trigger
+    # @param method_name [String,Symbol]
+    # @option include_private [Boolean]
+    # @raise NoMethodError
+    # @return [Object]
+    #
+    # @see Symbiont::Trigger#__actual_context__
+    #
+    # @since 0.1.0
+    def __actual_context__(method_name)
+      __directed_contexts__.find do |context|
+        context.respond_to?(method_name, false)
+      end || super
+    end
+  end
+end

data/lib/symbiont/trigger.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+# A class that controls the logic of closure execution in the context of other objects.
+# Responsible for dispatching the methods which should be executed in a certain context.
+# Delegation variations depends on the order of contexts.
+#
+# Trigger supports 3 contexts:
+#
+# * closure context;
+# * passed object's context;
+# * global ::Kernel context.
+#
+# If no context is able to respond to the required method - ContextNoMethodError exception is raised
+# (ContextNoMethodError inherits from NoMethodError).
+#
+# @api private
+# @since 0.1.0
+class Symbiont::Trigger < BasicObject
+  # Indicates the direction of context method resolving algorithm.
+  # Direction: initial context => outer context => kernel context.
+  #
+  # @return [Array<Symbol>]
+  #
+  # @api public
+  # @since 0.1.0
+  IOK = %i[__inner_context__ __outer_context__ __kernel_context__].freeze
+
+  # Indicates the direction of context method resolving algorithm.
+  # Direction: outer context => initial context => kernel context.
+  #
+  # @return [Array<Symbol>]
+  #
+  # @api public
+  # @since 0.1.0
+  OIK = %i[__outer_context__ __inner_context__ __kernel_context__].freeze
+
+  # Indicates the direction of context method resolving algorithm.
+  # Direction: outer context => kernel context => initial context.
+  #
+  # @return [Array<Symbol>]
+  #
+  # @api public
+  # @since 0.1.0
+  OKI = %i[__outer_context__ __kernel_context__ __inner_context__].freeze
+
+  # Indicates the direction of context method resolving algorithm.
+  # Direction: initial context => kernel context => outer context.
+  #
+  # @return [Array<Symbol>]
+  #
+  # @api public
+  # @since 0.1.0
+  IKO = %i[__inner_context__ __kernel_context__ __outer_context__].freeze
+
+  # Indicates the direction of context method resolving algorithm.
+  # Direction: kernel context => outer context => initial context.
+  #
+  # @return [Array<Symbol>]
+  #
+  # @api public
+  # @since 0.1.0
+  KOI = %i[__kernel_context__ __outer_context__ __inner_context__].freeze
+
+  # Indicates the direction of context method resolving algorithm.
+  # Direction: kernel context => initial context => outer context.
+  #
+  # @return [Array<Symbol>]
+  #
+  # api public
+  # @since 0.1.0
+  KIO = %i[__kernel_context__ __inner_context__ __outer_context__].freeze
+
+  # Is raised when closure (__outer_context__ instance attribute) isnt a Proc.
+  #
+  # @api public
+  # @since 0.1.0
+  IncompatibleclosureObjectError = ::Class.new(::ArgumentError)
+
+  # Is raised when chosen direction (__context_direction__ instance attribute) is not supported
+  # by a trigger. Supports only: OIK, OKI, IOK, IKO, KOI, KIO.
+  #
+  # @api public
+  # @since 0.1.0
+  IncompatibleContextDirectionError = ::Class.new(::ArgumentError)
+
+  # Is raised when no one is able to respond to the required method.
+  #
+  # @see #__actual_context__
+  #
+  # @api public
+  # @since 0.1.0
+  ContextNoMethodError = ::Class.new(::NoMethodError)
+
+  # Returns an object that should be used as the main context for
+  # context method resolving algorithm.
+  #
+  # @return [Object]
+  #
+  # @since 0.1.0
+  attr_reader :__inner_context__
+
+  # Returns a binding object of corresponding closure (see __closure__).
+  # Used as an outer context for context method resolving algorithm.
+  #
+  # @return [Object]
+  #
+  # @api private
+  # @since 0.1.0
+  attr_reader :__outer_context__
+
+  # Returns Kernel object that will be used as Kernel context for
+  # context method resolving algorithm.
+  #
+  # @return [::Kernel]
+  #
+  # @api private
+  # @since 0.1.0
+  attr_reader :__kernel_context__
+
+  # Returns proc object that will be triggered in many contexts: initial, outer and kernel.
+  #
+  # @return [Proc]
+  #
+  # @api private
+  # @since 0.1.0
+  attr_reader :__closure__
+
+  # Returns an array of symbols tha represents the direction of contexts.
+  # that represents an access method to each of them.
+  #
+  # @return [Array<Symbol>]
+  #
+  # @api private
+  # @since 0.1.0
+  attr_reader :__context_direction__
+
+  # Instantiates trigger object with corresponding initial context, closure and context resolving
+  # direction.
+  #
+  # @param initial_context [Object]
+  #   Main context which should be used for instance_eval on.
+  # @param closure [Proc]
+  #   closure that will be executed in a set of contexts (initial => outer => kernel by default).
+  #   An actual context (#__actual_context__) will be passed to a closure as an attribute.
+  # @raise IncompatibleclosureObjectError
+  #   Raises when received closure attribte isnt a Proc.
+  # @raise IncompatibleContextDirectionError
+  #   Is raised when chosen direction is not supported by a trigger.
+  #   Supports only OIK, OKI, IOK, IKO, KOI, KIO (see corresponding constant value above).
+  #
+  # @api private
+  # @since 0.1.0
+  def initialize(initial_context, closure, context_direction = IOK)
+    unless closure.is_a?(::Proc)
+      ::Kernel.raise(IncompatibleclosureObjectError, 'closure attribute should be a proc')
+    end
+
+    # rubocop:disable Layout/SpaceAroundKeyword
+    unless(context_direction == IOK || context_direction == OIK || context_direction == OKI ||
+           context_direction == IKO || context_direction == KOI || context_direction == KIO)
+      ::Kernel.raise(
+        IncompatibleContextDirectionError,
+        'Incompatible context direction attribute. ' \
+        'You should use one of this: OIK, OKI, IOK, IKO, KOI, KIO.'
+      )
+    end
+    # rubocop:enable Layout/SpaceAroundKeyword
+
+    @__closure__           = closure
+    @__context_direction__ = context_direction
+    @__inner_context__     = initial_context
+    @__outer_context__     = ::Kernel.eval('self', closure.binding)
+    @__kernel_context__    = ::Kernel
+  end
+
+  # Triggers a closure in multiple contexts.
+  #
+  # @return void
+  #
+  # @see #method_missing
+  #
+  # @api private
+  # @since 0.1.0
+  def __evaluate__
+    instance_eval(&__closure__)
+  end
+
+  # Returns a collection of the all contexts sorted by chosen direction.
+  #
+  # @return [Array<Object>]
+  #
+  # @see #__context_direction__
+  #
+  # @api private
+  # @since 0.1.0
+  def __directed_contexts__
+    __context_direction__.map { |direction| __send__(direction) }
+  end
+
+  # Returns the first context that is able to respond to the required method.
+  # The context is chosen in the context direction order (see #__context_direction__).
+  # Raises NoMethodError excepition when no one of the contexts are able to respond to
+  # the required method.
+  # Basicaly, abstract implementation raises NoMethodError.
+  #
+  # @param method_name [Symbol,String] Method that a context should respond to.
+  # @raise NoMethodError
+  #
+  # @see #__context_direction__
+  #
+  # @api private
+  # @since 0.1.0
+  def __actual_context__(method_name)
+    ::Kernel.raise ContextNoMethodError, "No one is able to respond to #{method_name}"
+  end
+
+  # Delegates method invocation to the corresponding actual context.
+  #
+  # @param method_name [String,Symbol] Method name
+  # @param arguments [Mixed] Method arguments
+  # @param block [Proc] Block
+  # @raise NoMethodError
+  #   Is rased when no one of the contexts are able to respond tothe required method.
+  # @return void
+  #
+  # @see #__actual_context__
+  #
+  # @api private
+  # @since 0.1.0
+  def method_missing(method_name, *arguments, &block) # rubocop:disable Style/MethodMissing
+    __actual_context__(method_name).send(method_name, *arguments, &block)
+  end
+
+  # Checks that the actual context is able to respond to a required method.
+  #
+  # @param method_name [String,Symbol] Method name
+  # @param _include_private [Boolean] Include private methods
+  # @raise NoMethodError
+  #   Is raised when no one of the contexts are able to respond to the required method.
+  # @return [Boolean] Is the actual context able to respond to the required method.
+  #
+  # @see #method_missing
+  # @see #__actual_context__
+  #
+  # @api private
+  # @since 0.1.0
+  # :nocov:
+  def respond_to_missing?(method_name, _include_private = false)
+    !!__actual_context__(method_name)
+  end
+  # :nocov:
+
+  # Returns a corresponding metehod object of the actual context.
+  #
+  # @param method_name [String,Symbol] Method name
+  # @raise NoMethodError
+  #   Is raised when no one of the contexts able to respond to the required method.
+  # @return [Method]
+  #
+  # @see #method_missing
+  # @see #respond_to_missing?
+  # @see #__actual_context__
+  #
+  # @api private
+  # @since 0.1.0
+  def method(method_name)
+    __actual_context__(method_name).method(method_name)
+  end
+end

data/lib/symbiont/version.rb

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

data/lib/symbiont.rb

@@ -1,5 +1,42 @@
 # frozen_string_literal: true
 
+# @api public
+# @since 0.1.0
 module Symbiont
   require_relative 'symbiont/version'
+  require_relative 'symbiont/trigger'
+  require_relative 'symbiont/public_trigger'
+  require_relative 'symbiont/private_trigger'
+  require_relative 'symbiont/executor'
+  require_relative 'symbiont/context'
+
+  # @see Symbiont::Trigger::IOK
+  # @api public
+  # @since 0.1.0
+  IOK = Trigger::IOK
+
+  # @see Symbiont::Trigger::OIK
+  # @api public
+  # @since 0.1.0
+  OIK = Trigger::OIK
+
+  # @see Symbiont::Trigger::OKI
+  # @api public
+  # @since 0.1.0
+  OKI = Trigger::OKI
+
+  # @see Symbiont::Trigger::IKO
+  # @api public
+  # @since 0.1.0
+  IKO = Trigger::IKO
+
+  # @see Symbiont::Trigger::IOK
+  # @api public
+  # @since 0.1.0
+  KOI = Trigger::KOI
+
+  # @see Symbiont::Trigger::KIO
+  # @api public
+  # @since 0.1.0
+  KIO = Trigger::KIO
 end

data/symbiont-ruby.gemspec

@@ -1,28 +1,40 @@
 # coding: utf-8
 
-lib = File.expand_path("../lib", __FILE__)
+lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "symbiont/version"
+require 'symbiont/version'
 
 Gem::Specification.new do |spec|
-  spec.name        = "symbiont-ruby"
-  spec.version     = Symbiont::VERSION
-  spec.authors     = ["Rustam Ibragimov"]
-  spec.email       = ["iamdaiver@icloud.com"]
-  spec.summary     = %q{Write a short summary, because RubyGems requires one.}
-  spec.description = %q{Write a longer description or delete this line.}
-  spec.homepage    = "https://github.com/0exp/symbiont-ruby"
-  spec.license     = "MIT"
+  spec.required_ruby_version = '>= 2.2.7'
 
-  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(test|spec|features)/})
-  end
+  spec.name          = 'symbiont-ruby'
+  spec.version       = Symbiont::VERSION
+  spec.author        = 'Rustam Ibragimov'
+  spec.email         = 'iamdaiver@icloud.com'
+  spec.summary       = 'Evaluate proc-objects in many contexts simultaneously'
+  spec.description   = 'Symbiont is a cool implementation of proc-objects execution algorithm: ' \
+                       'in the context of other object, but with the preservation of ' \
+                       'the closed environment of the proc object and with the ability of ' \
+                       'control the method dispatch inside it. A proc object is executed in ' \
+                       'three contexts: in the context of required object, in the context of '\
+                       'a closed proc\'s environment and in the global (Kernel) context.'
 
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.homepage      = 'https://github.com/0exp/symbiont-ruby'
+  spec.license       = 'MIT'
+  spec.bindir        = "bin"
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.16"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(spec|features)/})
+  end
+
+  spec.add_development_dependency "rspec",          "~> 3.7"
+  spec.add_development_dependency "rubocop",        "~> 0.53"
+  spec.add_development_dependency "rubocop-rspec",  "~> 1.24"
+  spec.add_development_dependency "simplecov",      "~> 0.15"
+  spec.add_development_dependency "simplecov-json", "~> 0.2"
+  spec.add_development_dependency "coveralls",      "~> 0.7"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "bundler"
 end