symbiont-ruby 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 981797ea2447acb615faac8cefe3fc02c0d05b0e
-  data.tar.gz: 42fc09dd324faddd33a20d0c908251fb16e149e3
+  metadata.gz: 2df520b8812cc17063343dec89c82fd4ef94feb5
+  data.tar.gz: 3ef7f4309989802c211aa91f234547c69ecc654a
 SHA512:
-  metadata.gz: cfce829ffc18d93300100a9f25d474ab3907d40be4c81ce6abe4952e4fa2d5818d7fbb8d25f1f765db28ea0d1dd810d2afdeeac065afbbc22707deb4319df572
-  data.tar.gz: 956452d617195d896ec245e70b0b2ce04d9b2c42d21df1edb7e012cff670f8c61a3d811abdce0dd80f4cfe1c52aa91648ffdcea407febcbd2e978e0e51587255
+  metadata.gz: 9c752120deaf778e7cf356b79beec8f2b471de4c3356993bd476239c25c23e7e1dbb540c5c2e39c37627aa6958c0306f209a97176ec038bc07767e9f5d01a708
+  data.tar.gz: 03f7fb48f8b91acd2e37260c4b6cfde7e18b4c2125ab4c2f2db56577c281f33bb4fc77a325ede3edb4a1a3e312afa37f85c4a69fb204b1d89cd96e763853e7b3

data/.rubocop.yml

@@ -39,6 +39,9 @@ Style/Documentation:
 Style/ClassAndModuleChildren:
   Enabled: false
 
+Style/IfUnlessModifier:
+  Enabled: false
+
 Style/EmptyCaseCondition:
   Enabled: false
 
@@ -54,6 +57,9 @@ Style/ParallelAssignment:
 Style/CommentedKeyword:
   Enabled: false
 
+Lint/HandleExceptions:
+  Enabled: false
+
 Layout/IndentArray:
   Enabled: false
 
@@ -70,7 +76,7 @@ Naming/VariableNumber:
   EnforcedStyle: snake_case
 
 Metrics/LineLength:
-  Max: 100
+  Max: 120
 
 Metrics/BlockLength:
   Exclude:

data/.travis.yml

@@ -9,4 +9,6 @@ rvm:
 sudo: false
 before_install: gem install bundler
 cache: bundler
-script: bundle exec rspec
+script:
+  - bundle exec rake yardoc
+  - bundle exec rspec

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
+## [0.2.0] 2018-04-22
+### Added
+- Logo ^_^ (special thanks to **Viktoria Karaulova**)
+- Support for multiple inner contexts: you can pass an array of objects as a context argument
+  to `Symbiont::Executor`. Each object will be used as an inner context in order they are passed.
+
+### Changed
+- Method signature: context direction should be passed as a named attribute `context_direction:`.
+
+  Affected methods:
+  - `Symbiont::Executor.evaluate`
+  - `Symbiont::Executor.evaluate_private`
+  - `Symbiont::Executor.public_method`
+  - `Symbiont::Executor.private_method`
+
 ## [0.1.0] - 2018-04-08
 - Release :)

data/README.md

@@ -1,4 +1,12 @@
-# Symbiont · [![Gem Version](https://badge.fury.io/rb/symbiont-ruby.svg)](https://badge.fury.io/rb/symbiont-ruby) [![Build Status](https://travis-ci.org/0exp/symbiont-ruby.svg?branch=master)](https://travis-ci.org/0exp/symbiont-ruby) [![Coverage Status](https://coveralls.io/repos/github/0exp/symbiont-ruby/badge.svg?branch=master)](https://coveralls.io/github/0exp/symbiont-ruby?branch=master)
+<p align="center"><img width="250" height="250" src="logo/symbiont_logo_circle.png" /></div>
+<p align="center">
+  <h1 align="center">
+    Symbiont<br />
+    <a href="https://badge.fury.io/rb/symbiont-ruby"><img src="https://badge.fury.io/rb/symbiont-ruby.svg"></a>
+    <a href="https://travis-ci.org/0exp/symbiont-ruby"><img src="https://travis-ci.org/0exp/symbiont-ruby.svg?branch=master"></a>
+    <a href="https://coveralls.io/github/0exp/symbiont-ruby?branch=master"><img src="https://coveralls.io/repos/github/0exp/symbiont-ruby/badge.svg?branch=master"></a>
+  </h1>
+</p>
 
 **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
@@ -46,6 +54,7 @@ require 'symbiont'
   - [Symbiont Mixin](#symbiont-mixin)
     - [Mixing a module with default delegation direction](#mixing-a-module-with-default-delegation-direction)
     - [Mixing a module with certain delegation direction](#mixing-a-module-with-certain-delegation-direction)
+  - [Multiple inner contexts](#multiple-inner-contexts)
 
 # Problems and motivaiton
 
@@ -193,15 +202,15 @@ Symbiont::KIO # Kernel Context => Inner Context  => Outer Context
 `Symbiont::Executor` allows you to execute proc objects in two modes of the delegation:
 
 - only public methods:
-  - `evaluate(required_context, [context_direction], &closure)`
+  - `evaluate(*required_contexts, [context_direction:], &closure)`
 - public and private methods:
-  - `evaluate_private(required_context, [context_direction], &closure)`
+  - `evaluate_private(*required_contexts, [context_direction:], &closure)`
 
 If no context is able to respond to the required method - `Symbiont::Trigger::ContextNoMethodError` exception is thrown.
 
 In the case when an unsupported direction value is used - `Symbiont::Trigger::IncompatibleContextDirectionError` exception is thrown.
 
-If proc object isnt passed to the executor - `Symbiont::Trigger::IncompatibleclosureObjectError` exception is thrown.
+If proc object isnt passed to the executor - `Symbiont::Trigger::UnprovidedClosureAttributeError` exception is thrown.
 
 #### Considering public methods only (.evaluate)
 
@@ -213,13 +222,13 @@ end
 # => "Data: inner_context"
 
 # with a custom delegation order
-Symbiont::Executor.evaluate(object, Symbiont::KIO) do
+Symbiont::Executor.evaluate(object, context_direction: Symbiont::KIO) do
   format_data(object_data)
 end
 # => "Data: kernel_context"
 
 # SimpleObject#object_data is a private method (inner_context)
-Symbiont::Executor.evaluate(object, Symbiont::IOK) do
+Symbiont::Executor.evaluate(object, context_direction: Symbiont::IOK) do
   format_data(object_data)
 end
 # => "Data: outer_context"
@@ -235,13 +244,13 @@ end
 # => "Data: inner_context"
 
 # with a custom delegation order
-Symbiont::Executor.evaluate_private(object, Symbiont::KIO) do
+Symbiont::Executor.evaluate_private(object, context_direction: Symbiont::KIO) do
   format_data(object_data)
 end
 # => "Data: kernel_context"
 
 # SimpleObject#object_data is a private method (inner_context)
-Symbiont::Executor.evaluate_private(object, Symbiont::IOK) do
+Symbiont::Executor.evaluate_private(object, context_direction: Symbiont::IOK) do
   format_data(object_data)
 end
 # => "Data: inner_data"
@@ -252,9 +261,9 @@ end
 `Symbiont::Executor` provides the possibility of obtaining the method object with consideration of the chosen delegation order:
 
 - only public methods:
-  - `public_method(method_name, required_context, [context_direction], &clojure)`
+  - `public_method(method_name, *required_contexts, [context_direction:], &clojure)`
 - public and private methods:
-  - `private_method(method_name, required_context, [context_direction], &clojure)`
+  - `private_method(method_name, *required_contexts, [context_direction:], &clojure)`
 
 If no context is able to respond to the required method - `Symbiont::Trigger::ContextNoMethodError` exception is thrown.
 
@@ -268,11 +277,11 @@ Symbiont::Executor.public_method(:object_data, object, &closure)
 # => #<Method: SimpleObject#object_data>
 
 # with a custom delegation order
-Symbiont::Executor.public_method(:object_data, object, Symbiont::OIK, &closure)
+Symbiont::Executor.public_method(:object_data, object, context_direction: Symbiont::OIK, &closure)
 # => (main) #<Method: SimpleObject(object)#object_data>
 
 # SimpleObject#object_data is a private method
-Symbiont::Executor.public_method(:object_data, object, Symbiont::IOK, &closure)
+Symbiont::Executor.public_method(:object_data, object, context_direction: Symbiont::IOK, &closure)
 # => (main) #<Method: SimpleObject(object)#object_data>
 ```
 
@@ -284,17 +293,17 @@ Symbiont::Executor.private_method(:object_data, object, &clojure)
 # => #<Method: SimpleObject#object_data>
 
 # with a custom delegation order
-Symbiont::Executor.private_method(:object_data, object, Symbiont::KIO, &clojure)
+Symbiont::Executor.private_method(:object_data, object, context_direction: Symbiont::KIO, &clojure)
 # => #<Method: Kernel.object_data>
 
 # SimpleObject#object_data is a private_method
-Symbiont::Executor.private_method(:object_data, object, Symbiotn::IKO, &clojure)
+Symbiont::Executor.private_method(:object_data, object, context_direction: Symbiotn::IKO, &clojure)
 # => #<Method: SimpleObject#object_data>
 ```
 
 ## Symbiont Mixin
 
-'Symbiont:: Context' is a mixin that allows any object to call proc objects in the context of itself as Symbiont::Executor
+`Symbiont::Context` is a mixin that allows any object to call proc objects in the context of itself as `Symbiont::Executor`.
 
 You can specify the default direction of the context delegation. `Symbiont::IOK` is used by default.
 
@@ -354,6 +363,33 @@ SimpleObject.new.evaluate(Symbiont::IOK) { object_data }
 # => object.object_data => "inner_context"
 ```
 
+## Multiple inner contexts
+
+
+`Symbiont::Executor` allows you to work with multiple inner contexts (can receive a set of objects instead of the one main object).
+Each object will be used as an inner context in order they are passed.
+The method will be addressed to the object that responds first (in accordance with a chosen delegation order).
+
+```ruby
+# Usage:
+
+Symbiont::Executor.evaluate(object_a, object_b, context_direction: Symbiont::IOK, &closure)
+Symbiont::Executor.evaluate_private(object_a, object_b, context_direction: Symbiont::IOK, &closure)
+Symbiont::Executor.publc_method(:method_name, object_a, object_b, context_direction: Symbiont::IOK, &closure)
+Symbiont::Executor.private_method(:method_name, object_a, object_b, context_direction: Symbiont::IOK, &closure)
+
+# Example
+
+object_a.info # => "object_info"
+object_b.data # => "object_data"
+
+closure = proc { "#{info} #{data}" }
+
+Symbiont::Executor.evaluate(object_a, object_b, &closure) # => "object_info object_data"
+Symbiont::Executor.public_method(:data, object_a, object_b, &closure).call # => "object_data"
+Symbiont::Executor.public_method(:info, object_a, object_b, &closure).call # => "object_info"
+```
+
 # Contributing
 
 - Fork it ( https://github.com/0exp/symbiont-ruby/fork )
@@ -366,6 +402,9 @@ SimpleObject.new.evaluate(Symbiont::IOK) { object_data }
 
 Released under MIT License.
 
-# About
+# Authors
+
+[Logo](https://github.com/0exp/symbiont-ruby/tree/master/logo) was created by **Viktoria Karaulova** (my special thanks ^_^).
+
+Project was created by **Rustam Ibragimov**.
 
-Created by Rustam Ibragimov.

data/Rakefile

@@ -1,6 +1,30 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'yard'
 
 RSpec::Core::RakeTask.new(:rspec)
 
-task :default => :rspec
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files = Dir[Pathname.new(__FILE__).join('../lib/**/*.rb')]
+  t.options = %w[--protected --private]
+end
+
+task default: :rspec
+
+task yardoc: :doc do
+  undocumented_code_objects = YARD::Registry.tap(&:load).select do |code_object|
+    code_object.docstring.empty?
+  end
+
+  if undocumented_code_objects.empty?
+    puts 'YARD COVERAGE [SUCCESS] => 100% documentation coverage!'
+  else
+    failing_code_objects = undocumented_code_objects.map do |code_object|
+      "- #{code_object.class} => #{code_object.to_s}"
+    end.join("\n")
+
+    abort("YARD COVERAGE [FAILURE] => No documentation found for: \n #{failing_code_objects}")
+  end
+end

data/lib/symbiont.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# Main Symbiont namespace.
+#
 # @api public
 # @since 0.1.0
 module Symbiont
@@ -10,32 +12,50 @@ module Symbiont
   require_relative 'symbiont/executor'
   require_relative 'symbiont/context'
 
+  # Method delegation order alias (inner_contexts => outer_context => kernel_context).
+  #
   # @see Symbiont::Trigger::IOK
+  #
   # @api public
   # @since 0.1.0
   IOK = Trigger::IOK
 
+  # Method delegation order alias (outer_context => inner_contexts => kernel_context).
+  #
   # @see Symbiont::Trigger::OIK
+  #
   # @api public
   # @since 0.1.0
   OIK = Trigger::OIK
 
+  # Method delegation order alias (outer_context => kernel_context => inner_contexts).
+  #
   # @see Symbiont::Trigger::OKI
+  #
   # @api public
   # @since 0.1.0
   OKI = Trigger::OKI
 
+  # Method delegation order alias (inner_contexts => kernel_context => outer_context).
+  #
   # @see Symbiont::Trigger::IKO
+  #
   # @api public
   # @since 0.1.0
   IKO = Trigger::IKO
 
+  # Method delegation order alias (kernel_context => outer_context => inner_contexts).
+  #
   # @see Symbiont::Trigger::IOK
+  #
   # @api public
   # @since 0.1.0
   KOI = Trigger::KOI
 
+  # Method delegation order alias (kernel_context => inner_contexts => outer_context).
+  #
   # @see Symbiont::Trigger::KIO
+  #
   # @api public
   # @since 0.1.0
   KIO = Trigger::KIO

data/lib/symbiont/context.rb

@@ -4,9 +4,10 @@ module Symbiont
   class << self
     # Factory method for a mixin module that provides an ability to invoke procs and lambdas
     # in many contexts to any object. Mixes up special methods that delegate execution logic to
-    # to a special mediator object (Symbiont::Executor).
+    # to a special mediator object (`Symbiont::Executor`).
     #
-    # @param default_context_direction [Array<Symbol>] Delegation order.
+    # @param default_context_direction [Array<Symbol>]
+    #   Delegation order `for Symbiont::Executor`. Trigger::IOK is used by default.
     # @return [Module]
     #
     # @see Symbiont::Executor
@@ -17,32 +18,36 @@ module Symbiont
     # @api public
     # @since 0.1.0
     #
-    # rubocop:disable Naming/MethodName, Metrics/LineLength
+    # rubocop:disable Naming/MethodName
     def Context(default_context_direction = Trigger::IOK)
       Module.new do
         define_method :evaluate do |context_direction = default_context_direction, &closure|
-          Executor.evaluate(self, context_direction, &closure)
+          Executor.evaluate(self, context_direction: context_direction, &closure)
         end
 
         define_method :evaluate_private do |context_direction = default_context_direction, &closure|
-          Executor.evaluate_private(self, context_direction, &closure)
+          Executor.evaluate_private(self, context_direction: context_direction, &closure)
         end
 
         define_method :public_method do |method_name, context_direction = default_context_direction, &closure|
-          Executor.public_method(self, method_name, context_direction, &closure)
+          Executor.public_method(self, method_name, context_direction: context_direction, &closure)
         end
 
         define_method :private_method do |method_name, context_direction = default_context_direction, &closure|
-          Executor.private_method(self, method_name, context_direction, &closure)
+          Executor.private_method(self, method_name, context_direction: context_direction, &closure)
         end
       end
     end
-    # rubocop:enable Naming/MethodName, Metrics/LineLength
+    # rubocop:enable Naming/MethodName
   end
 
+  # Default Context mixin that provides an ability to invoke procs and lambdas
+  # in many contexts to any object. Mixes up special methods that delegate execution logic to
+  # to a special mediator object (`Symbiont::Executor`). Uses Symbiont::Trigger::IOK delegation order.
+  #
   # @see Symbiont.Context
   #
   # @api public
   # @since 0.1.0
-  Context = Context()
+  Context = Context(Trigger::IOK)
 end

data/lib/symbiont/executor.rb

@@ -2,7 +2,7 @@
 
 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.
+  # Acts as a factory for trigerrs and an execution-mediator for procs.
   #
   # @api public
   # @since 0.1.0
@@ -11,40 +11,74 @@ module Symbiont
       # 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 required_contexts [Array<Object>]
+      #   A set of objects that should be used as the main context series for method resolving
+      #   algorithm.
       # @param context_direction [Array<Symbol>]
+      #   An array of symbols that represents the direction of contexts. Possible values:
+      #
+      #    - Symbiont::IOK
+      #    - Symbiont::OIK
+      #    - Symbiont::OKI
+      #    - Symbiont::IKO
+      #    - Symbiont::KOI
+      #    - Symbiont::KIO
       # @param closure [Proc]
+      #   Proc object that will be evaluated in many contexts: initial, outer and kernel.
       # @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__
+      def evaluate(*required_contexts, context_direction: Trigger::IOK, &closure)
+        public_trigger(*required_contexts, context_direction: 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 required_contexts [Array<Object>]
+      #   A set of objects that should be used as the main context series for method resolving
+      #   algorithm.
       # @param context_direction [Array<Symbol>]
+      #   An array of symbols that represents the direction of contexts. Possible values:
+      #
+      #     - Symbiont::IOK
+      #     - Symbiont::OIK
+      #     - Symbiont::OKI
+      #     - Symbiont::IKO
+      #     - Symbiont::KOI
+      #     - Symbiont::KIO
       # @param closure [Proc]
+      #   Proc object that will be evaluated in many contexts: initial, outer and kernel.
       # @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__
+      def evaluate_private(*required_contexts, context_direction: Trigger::IOK, &closure)
+        private_trigger(*required_contexts, context_direction: 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 required_contexts [Array<Object>]
+      #   A set of objects that should be used as the main context series for method resolving
+      #   algorithm.
       # @param context_direction [Array<Symbol>]
+      #   An array of symbols that represents the direction of contexts. Possible values:
+      #
+      #     - Symbiont::IOK
+      #     - Symbiont::OIK
+      #     - Symbiont::OKI
+      #     - Symbiont::IKO
+      #     - Symbiont::KOI
+      #     - Symbiont::KIO
       # @param closure [Proc]
+      #   Proc object that will be evaluated in many contexts: initial, outer and kernel.
       # @return [Symbiont::PublicTrigger]
       #
       # @see Symbiont::PublicTrigger
@@ -52,16 +86,27 @@ module Symbiont
       #
       # @api public
       # @since 0.1.0
-      def public_trigger(required_context, context_direction = Trigger::IOK, &closure)
-        PublicTrigger.new(required_context, closure, context_direction)
+      def public_trigger(*required_contexts, context_direction: Trigger::IOK, &closure)
+        PublicTrigger.new(*required_contexts, context_direction: context_direction, &closure)
       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 required_contexts [Array<Object>]
+      #   A set of objects that should be used as the main context series for method resolving
+      #   algorithm.
       # @param context_direction [Array<Symbol>]
+      #   An array of symbols that represents the direction of contexts. Possible values:
+      #
+      #     - Symbiont::IOK
+      #     - Symbiont::OIK
+      #     - Symbiont::OKI
+      #     - Symbiont::IKO
+      #     - Symbiont::KOI
+      #     - Symbiont::KIO
       # @param closure [Proc]
+      #   Proc object that will be evaluated in many contexts: initial, outer and kernel.
       # @return [Symbiont::PrivateTrigger]
       #
       # @see Symbiont::PrivateTrigger
@@ -69,42 +114,62 @@ module Symbiont
       #
       # @api public
       # @since 0.1.0
-      def private_trigger(required_context, context_direction = Trigger::IOK, &closure)
-        PrivateTrigger.new(required_context, closure, context_direction)
+      def private_trigger(*required_contexts, context_direction: Trigger::IOK, &closure)
+        PrivateTrigger.new(*required_contexts, context_direction: context_direction, &closure)
       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]
+      # @param method_name [Symbol,String] A name of required method.
+      # @param required_contexts [Array<Object>]
+      #   A set of objects that should be used as the main context series for method resolving
+      #   algorithm.
+      #   An array of symbols that represents the direction of contexts. Possible values:
+      #
+      #     - Symbiont::IOK
+      #     - Symbiont::OIK
+      #     - Symbiont::OKI
+      #     - Symbiont::IKO
+      #     - Symbiont::KOI
+      #     - Symbiont::KIO
+      # @param closure [Proc] Proc object that will be used as outer-context for method resolution.
       # @return [Method]
       #
+      # @see Symbiont::PublicTrigger
       # @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)
+      def public_method(method_name, *required_contexts, context_direction: Trigger::IOK, &closure)
+        public_trigger(*required_contexts, context_direction: 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]
+      # @param method_name [Symbol,String] A name of required method.
+      # @param required_contexts [Array<Object>]
+      #   A set of objects that should be used as the main context series for method resolving
+      #   algorithm.
+      #   An array of symbols that represents the direction of contexts. Possible values:
+      #
+      #     - Symbiont::IOK
+      #     - Symbiont::OIK
+      #     - Symbiont::OKI
+      #     - Symbiont::IKO
+      #     - Symbiont::KOI
+      #     - Symbiont::KIO
+      # @param closure [Proc] Proc object that will be used as outer-context for method resolution.
       # @return [Method]
       #
+      # @see Symbiont::PrivateTrigger
       # @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)
+      def private_method(method_name, *required_contexts, context_direction: Trigger::IOK, &closure)
+        private_trigger(*required_contexts, context_direction: context_direction, &closure).method(method_name)
       end
     end
   end