symbiont-ruby 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2c69f2b2d2c2769613e8800db568088f6e865757
-  data.tar.gz: 442d929687477682c2aefb5f338b0d796abaed0d
+  metadata.gz: 981797ea2447acb615faac8cefe3fc02c0d05b0e
+  data.tar.gz: 42fc09dd324faddd33a20d0c908251fb16e149e3
 SHA512:
-  metadata.gz: fddf417344f3d6fc069d0cddeea336cc21c885e3d8255b961fa241e806c440fdf2b58200a6f40ff88fa307b8efb3f54aea89c7af469b9957cf3c9010dd1df70a
-  data.tar.gz: bab423028886def5d5d1da03e445ac5c6d0e084e423545b693bbbedb2da84e3fe50a574b72a774aa1fc070a7e365195e7044e8d0b1497ef58d49c6bac9eecc7b
+  metadata.gz: cfce829ffc18d93300100a9f25d474ab3907d40be4c81ce6abe4952e4fa2d5818d7fbb8d25f1f765db28ea0d1dd810d2afdeeac065afbbc22707deb4319df572
+  data.tar.gz: 956452d617195d896ec245e70b0b2ce04d9b2c42d21df1edb7e012cff670f8c61a3d811abdce0dd80f4cfe1c52aa91648ffdcea407febcbd2e978e0e51587255

data/.gitignore

@@ -1,11 +1,10 @@
 /.bundle/
 /.yardoc
 /_yardoc/
+/Gemfile.lock
 /coverage/
 /doc/
 /pkg/
 /spec/reports/
 /tmp/
-
-# rspec failure tracking
 .rspec_status

data/.hound.yml

@@ -0,0 +1,2 @@
+ruby:
+  config_file: .rubocop.yml

data/.rspec

@@ -1,3 +1,3 @@
---format documentation
 --color
+--format=progress
 --require spec_helper

data/.rubocop.yml

@@ -0,0 +1,119 @@
+require: rubocop-rspec
+
+AllCops:
+  DisplayCopNames:   true
+  DisplayStyleGuide: true
+  TargetRubyVersion: 2.4.3
+  Include:
+    - lib/**/*
+    - spec/**/*
+  Exclude:
+    - bin/**/*
+    - Gemfile
+    - Rakefile
+    - symbiont-ruby.gemspec
+
+Style/SingleLineMethods:
+  Exclude:
+    - spec/**/*
+
+Style/RescueModifier:
+  Exclude:
+    - spec/**/*
+
+Style/AsciiComments:
+  Enabled: false
+
+Style/Alias:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/DoubleNegation:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/EmptyCaseCondition:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Style/InverseMethods:
+  Enabled: false
+
+Style/ParallelAssignment:
+  Enabled: false
+
+Style/CommentedKeyword:
+  Enabled: false
+
+Layout/IndentArray:
+  Enabled: false
+
+Lint/AmbiguousRegexpLiteral:
+  Enabled: false
+
+Lint/UnusedMethodArgument:
+  Enabled: false
+
+Naming/FileName:
+  Enabled: false
+
+Naming/VariableNumber:
+  EnforcedStyle: snake_case
+
+Metrics/LineLength:
+  Max: 100
+
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+Metrics/MethodLength:
+  Max: 20
+
+RSpec/ContextWording:
+  Enabled: false
+
+RSpec/HookArgument:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Max: 6
+
+RSpec/MessageSpies:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/DescribeClass:
+  Enabled: false
+
+RSpec/LetSetup:
+  Enabled: false
+
+RSpec/AnyInstance:
+  Enabled: false
+
+RSpec/MultipleSubjects:
+  Enabled: false
+
+RSpec/EmptyLineAfterSubject:
+  Enabled: false

data/.travis.yml

@@ -1,5 +1,12 @@
-sudo: false
 language: ruby
 rvm:
-  - 2.4.2
-before_install: gem install bundler -v 1.16.0
+- 2.2.9
+- 2.3.6
+- 2.4.3
+- 2.5.0
+- ruby-head
+
+sudo: false
+before_install: gem install bundler
+cache: bundler
+script: bundle exec rspec

data/.yardopts

@@ -0,0 +1 @@
+--protected --private --markup markdown

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2018-04-08
+- Release :)

data/README.md

@@ -1,10 +1,11 @@
-# Symbiont::Ruby
+# 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)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/symbiont/ruby`. To experiment with that code, run `bin/console` for an interactive prompt.
+**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.
 
-TODO: Delete this and the text above, and describe your gem
-
-## Installation
+# Installation
 
 Add this line to your application's Gemfile:
 
@@ -14,30 +15,357 @@ gem 'symbiont-ruby'
 
 And then execute:
 
-    $ bundle
+```shell
+$ bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install symbiont-ruby
+```shell
+$ gem install symbiont-ruby
+```
+
+After all:
+
+```ruby
+require 'symbiont'
+```
+
+# Table of contents
+
+- [Problem and motivation](#problems-and-motivaiton)
+- [Usage](#usage)
+  - [Context management](#context-management)
+  - [Supported method delegation directions](#supported-methods-delegation-directions)
+  - [Proc object invokation](#proc-object-invokation)
+    - [Considering public methods only (.evaluate)](#considering-public-methods-only-evaluate)
+    - [Considering private and public methods (.evaluate_private)](#considering-private-and-public-methods-evaluate_private)
+  - [Getting method-objects (Method)](#getting-method-objects-method)
+    - [Considering public methods only (.public_method)](#considering-public-methods-only-public_method)
+    - [Considering public and private methods (.private_method)](#considering-public-and-private-methods-private_method)
+  - [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)
+
+# Problems and motivaiton
+
+The main problem of `instance_eval` / `instance exec` / `class_eval` / `class_exec` is that the binding (self)
+inside a proc-objec is replaced with the object in where a proc object is executed. This allows you to delegate all methods closed by a proc to another object.
+But this leads to the fact that the proc object loses access to the original closed environment.
+Symbiont solves this problem by allowing to proc to be executed in the required context while maintaining access to the methods of the closed environemnt
+(including the global context).
+
+---
+
+A prroblem with `instance_eval` / `instance_exec` / `class_eval` / `class_exec`:
+
+```ruby
+class TableFactory
+  def initialize
+    @primary_key = nil
+  end
+
+  def primary_key(key)
+    @primary_key = key
+  end
+end
+
+class Migration
+  class << self
+    def create_table(&block)
+      TableFactory.new.tap do |table|
+        table.instance_eval(&block) # NOTE: closure invokation
+      end
+    end
+  end
+end
+
+class CreateUsers < Migration
+  class << self
+    def up
+      create_table do # NOTE: failing closure
+        primary_key(generate_pk(:id))
+      end
+    end
+
+    def generate_pk(name)
+      "secure_#{name}"
+    end
+  end
+end
+
+CreateUsers.up
+# => NoMethodError: undefined method `generate_pk' for #<TableFactory:0x00007f8560ca4a58>
+```
+
+Symbiont solves this:
+
+```ruby
+require 'symbiont'
+
+class Migration
+  class << self
+    def create_table(&block)
+      TableFactory.new.tap do |table|
+        Symbiont::Executor.evaluate(table, &block) # NOTE: intercept closure invokation by Symbiont
+      end
+    end
+  end
+end
+
+CreateUsers.up
+# => #<TableFactory:0x00007f990527f268 @primary_key="secure_id">
+```
+
+---
+
+Proc-object is executed in three contexts at the same time:
+
+- in the context of closure;
+- in the context of required object;
+- in the global context (Kernel).
+
+Methods (called internally) are delegated to the context that is first able to respond.
+The order of context selection depends on the corresponding context direction parameter.
+By default the delegation order is: object context => closure context => global context.
+If no context is able to respond to the method, an exception is thrown (`Symbiont::Trigger::ContextNoMethodError`).
+Symbiont can consider the visiblity of methods when executing.
+
+
+# Usage
+
+## Context management
+
+Imagine that in a real application we have the following gode and the corresponding closure:
+
+```ruby
+def object_data
+  'outer_context'
+end
+
+class SimpleObject
+  def format_data(data)
+    "Data: #{data}"
+  end
+
+  def object_data
+    'inner_context'
+  end
+end
+
+class << Kernel
+  def object_data
+    'kernel_data'
+  end
+end
+
+object = SimpleObject.new
+
+closure = proc { format_data(object_data) } # NOTE: our closure
+```
+
+How a proc object will be processed, which context will be selected, how to make sure that nothing is broken - welcome to Symbiont.
+
+## Supported methods delegation directions
+
+Delegation order is set by a constant and passed as a parameter in the execution of the proc
+and the generation of a special mixin module, allowing any class or instance to become a symbiont.
+
+Supported contexts
+
+- inner context  - an object where proc is executed;
+- outer context  - external environment of the proc object;
+- kernel context - global Kernel context.
+
+Symbiont::IOK is chosen by default (`inner context => outer context => kernel context`)
+
+```ruby
+Symbiont::IOK # Inner Context  => Outer Context  => Kernel Context (DEFAULT)
+Symbiont::OIK # Outer Context  => Inner Context  => Kernel Context
+Symbiont::OKI # Outer Context  => Kernel Context => Inner Context
+Symbiont::IKO # Inner Context  => Kernel Context => Outer Context
+Symbiont::KOI # Kernel Context => Outer Context  => Inner Context
+Symbiont::KIO # Kernel Context => Inner Context  => Outer Context
+```
+
+## Proc object invokation
+
+`Symbiont::Executor` allows you to execute proc objects in two modes of the delegation:
+
+- only public methods:
+  - `evaluate(required_context, [context_direction], &closure)`
+- public and private methods:
+  - `evaluate_private(required_context, [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.
+
+#### Considering public methods only (.evaluate)
+
+```ruby
+# with default delegation order (Symbiont::IOK)
+Symbiont::Executor.evaluate(object) do
+  format_data(object_data)
+end
+# => "Data: inner_context"
+
+# with a custom delegation order
+Symbiont::Executor.evaluate(object, 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
+  format_data(object_data)
+end
+# => "Data: outer_context"
+```
+
+#### Considering private and public methods (.evaluate_private)
+
+```ruby
+# with default delegation order (Symbiont::IOK)
+Symbiont::Executor.evaluate_private(object) do
+  format_data(object_data)
+end
+# => "Data: inner_context"
+
+# with a custom delegation order
+Symbiont::Executor.evaluate_private(object, 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
+  format_data(object_data)
+end
+# => "Data: inner_data"
+```
+
+## Getting method-objects (Method)
+
+`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 and private methods:
+  - `private_method(method_name, required_context, [context_direction], &clojure)`
+
+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.
+
+#### Considering public methods only (.public_method)
+
+```ruby
+# with default delegation order (Symbiont::IOK)
+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)
+# => (main) #<Method: SimpleObject(object)#object_data>
+
+# SimpleObject#object_data is a private method
+Symbiont::Executor.public_method(:object_data, object, Symbiont::IOK, &closure)
+# => (main) #<Method: SimpleObject(object)#object_data>
+```
+
+#### Considering public and private methods (.private_method)
+
+```ruby
+# with default delegation order (Symbiont::IOK)
+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)
+# => #<Method: Kernel.object_data>
+
+# SimpleObject#object_data is a private_method
+Symbiont::Executor.private_method(:object_data, object, 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
+
+You can specify the default direction of the context delegation. `Symbiont::IOK` is used by default.
+
+#### Mixing a module with default delegation direction
 
-## Usage
+```ruby
+class SimpleObject
+  include Symbiont::Context # Symbiont::IOK direction is used by default
+
+  # #evaluate([context_direction = Symbiont::IOK], &closure)
+  # #evaluate_private([context_direction = Symbiont::IOK], &closure)
+  # #public_method(method_name, [context_direction = Symbiont::IOK])
+  # #private_method(method_name, [context_direction = Symbiont::IOK])
 
-TODO: Write usage instructions here
+  extend Symbiont::Context # Symbiont::IOK direction is used by default
 
-## Development
+  # .evaluate([context_direction = Symbiont::IOK], &closure)
+  # .evaluate_private([context_direction = Symbiont::IOK], &closure)
+  # .public_method(method_name, [context_direction = Symbiont::IOK])
+  # .private_method(method_name, [context_direction = Symbiont::IOK])
+end
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+def object_data
+  'outer_context'
+end
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+SimpleObject.new.evaluate { object_data }
+# => object.object_data => "inner_context"
+
+SimpleObject.new.evaluate(Symbiont::OIK) { object_data }
+# => object_data() => "outer_context"
+```
+
+#### Mixing a module with certain delegation direction
+
+```ruby
+class SimpleObject
+  include Symbiont::Context(Symboiont::KOI) # use a custom direction
+
+  # #evaluate([context_direction = Symbiont::KOI], &closure)
+  # #evaluate_private([context_direction = Symbiont::KOI], &closure)
+  # #public_method(method_name, [context_direction = Symbiont::KOI])
+  # #private_method(method_name, [context_direction = Symbiont::KOI])
+
+  extend Symbiont::Context(Symbiont::KOI) # use a custom direction
+
+  # .evaluate([context_direction = Symbiont::KOI], &closure)
+  # .evaluate_private([context_direction = Symbiont::KOI], &closure)
+  # .public_method(method_name, [context_direction = Symbiont::KOI])
+  # .private_method(method_name, [context_direction = Symbiont::KOI])
+end
+
+SimpleObject.new.evaluate { object_data }
+# => Kernel.object_data => "kernel_context"
+
+SimpleObject.new.evaluate(Symbiont::IOK) { object_data }
+# => object.object_data => "inner_context"
+```
 
-## Contributing
+# Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/symbiont-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+- Fork it ( https://github.com/0exp/symbiont-ruby/fork )
+- Create your feature branch (`git checkout -b my-new-feature`)
+- Commit your changes (`git commit -am 'Add some feature'`)
+- Push to the branch (`git push origin my-new-feature`)
+- Create new Pull Request
 
-## License
+# License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Released under MIT License.
 
-## Code of Conduct
+# About
 
-Everyone interacting in the Symbiont::Ruby project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/symbiont-ruby/blob/master/CODE_OF_CONDUCT.md).
+Created by Rustam Ibragimov.

data/Rakefile

@@ -1,6 +1,6 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new(:rspec)
 
-task :default => :spec
+task :default => :rspec

data/bin/console

@@ -1,14 +1,7 @@
 #!/usr/bin/env ruby
 
-require "bundler/setup"
-require "symbiont/ruby"
+require 'bundler/setup'
+require 'symbiont/ruby'
 
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "irb"
-IRB.start(__FILE__)
+require 'pry'
+Pry.start

data/lib/symbiont/context.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+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).
+    #
+    # @param default_context_direction [Array<Symbol>] Delegation order.
+    # @return [Module]
+    #
+    # @see Symbiont::Executor
+    # @see Symbiont::Trigger
+    # @see Symbiont::PublicTrigger
+    # @see Symbiont::PrivateTrigger
+    #
+    # @api public
+    # @since 0.1.0
+    #
+    # rubocop:disable Naming/MethodName, Metrics/LineLength
+    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)
+        end
+
+        define_method :evaluate_private do |context_direction = default_context_direction, &closure|
+          Executor.evaluate_private(self, 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)
+        end
+
+        define_method :private_method do |method_name, context_direction = default_context_direction, &closure|
+          Executor.private_method(self, method_name, context_direction, &closure)
+        end
+      end
+    end
+    # rubocop:enable Naming/MethodName, Metrics/LineLength
+  end
+
+  # @see Symbiont.Context
+  #
+  # @api public
+  # @since 0.1.0
+  Context = Context()
+end