affect 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0ef9c069aa2f0077d7cbf108e9f9a36aaf2a1808fdc1636d37e40333b6cfc2e0
+  data.tar.gz: 54e9f068ed3fecdb8dd624efb41b9540ecb1259b569636fca193a7c0fc27e172
+SHA512:
+  metadata.gz: d2aadb70ccf3ea71c0dfa794cbe33424a4b2ab74ec6208d0137e3664149320a748199dc6c4944dd677ed3f4ace979e6411878165918e4bbd68c539eadbaa02cc
+  data.tar.gz: 983d269425f777d7aae8ce64251b293a170a8dc5dfd7a57a46bc0827e7e81c0bfaadd3111d9e578a15676d0621526278054a17c06e6b7c7bd098f2f8d26dfc66

data/.gitignore

@@ -0,0 +1,50 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,19 @@
+PATH
+  remote: .
+  specs:
+    affect (0.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    minitest (5.11.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  affect!
+  minitest (= 5.11.3)
+
+BUNDLED WITH
+   1.17.2

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Sharon Rosner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,300 @@
+# Affect - structured side effects for functional Ruby
+
+[INSTALL](#installing-affect) |
+[TUTORIAL](#getting-started) |
+[EXAMPLES](examples) |
+
+> Affect | əˈfɛkt | verb [with object] have an effect on; make a difference to.
+
+## What is Affect
+
+Affect is a tiny Ruby gem providing a way to isolate and handle side-effects in
+functional programs. Affect implements algebraic effects in Ruby, but can also
+be used to implement patterns that are orthogonal to object-oriented
+programming, such as inversion of control and dependency injection.
+
+> **Note**: Affect does not pretend to be a *complete, theoretically correct*
+> implementation of algebraic effects. Affect concentrates on the idea of 
+> [effect contexts](#the-effect-context). It does not deal with continuations,
+> asynchrony, or any other concurrency constructs.
+
+## Installing Affect
+
+```bash
+$ gem install affect
+```
+
+Or add it to your Gemfile, you know the drill.
+
+## Getting Started
+
+Algebraic effects introduces the concept of effect handlers, little pieces of
+code that are provided by the caller, and invoked by the callee using a uniform
+interface. An example of algebraic effects might be logging. Normally, if we
+wanted to log a certain message to `STDOUT` or to a file, we wold do the
+following:
+
+```ruby
+def mul(x, y)
+  # assume LOG is a global logger object
+  LOG.info("called with #{x}, #{y}")
+  x * y
+end
+
+puts "Result: #{ mul(2, 3) }"
+```
+
+The act of logging is a side-effect of our computation. We need to have a global
+`LOG` object, and we cannot test the functioning of the `mul` method in
+isolation. What if we wanted to be able to plug-in a custom logger, or intercept
+calls to the logger?
+
+Affect provides a solution for such problems by implementing a uniform, 
+composable interface for isolating and handling side effects:
+
+```ruby
+require 'affect'
+
+def mul(x, y)
+  # assume LOG is a global logger object
+  Affect :log, "called with #{x}, #{y}"
+  x * y
+end
+
+Affect.wrap {
+  puts "Result: #{ mul(2, 3) }"
+}.on(:log) { |message|
+  puts "#{Time.now} #{message} (this is a log message)"
+}.()
+```
+
+In the example above, we replace the call to `LOG.info` with an invocation of a
+`LogIntent` instance. When the intent is passed to `Affect`, the corresponding
+handler is called in order to perform the intent.
+
+In essence, by separating the performance of side effects into effect intents,
+and effect handlers, we have separated the what from the how. The `mul` method
+is no longer concerned with how to log the message it needs to log. There's no 
+hardbaked reference to a `Log` object, and no logging API to follow. Instead,
+the *intent* to log a message is passed on to `Affect`, which in turn runs the
+correct handler that actually does the logging.
+
+## Performing side effects
+
+Side effects are performed by calling `Affect.perform` or simply `Affect()` with
+a specification of the effect to be performed:
+
+```ruby
+Affect.perform :foo
+
+# or:
+Affect :foo
+```
+
+You can also pass along more arguments. Those will in turn be passed to the
+effect handler:
+
+```ruby
+Affect :log, 'my message'
+```
+
+Effects can be represented using any Ruby object, but in a relatively complex
+application might be best represented using classes or structs signifying the
+*intent* to perform an effect:
+
+```ruby
+LogIntent = Struct.new(:msg)
+
+Affect LogIntent.new('my message')
+```
+
+When representing effects using symbols, Affect provides a shorthand way to 
+perform effects by calling methods directly on the `Affect` module:
+
+```ruby
+Affect.log('my message')
+```
+
+Finally, effects should be performed inside of an effect context, by invoking
+`Affect::Context#call`. Mostly, you'll want to use the callable shorthand 
+`.() { ... }`:
+
+```ruby
+def add(x, y)
+  Affect :log, "adding #{x} and #{y}..."
+  x + y
+end
+
+Affect.on(:log) { |msg| puts "#{Time.now} #{msg}" }.() {
+  result = add(2, 2)
+  puts "result: #{result}"
+}
+```
+
+## handling side effects
+
+Side effect handlers can be defined using the `Affect.on` or `Affect.handle`
+methods. `Affect.on` is used to register one or more effect handlers:
+
+```ruby
+# register a single effect handler
+Affect.on(:log) { |msg| puts "#{Time.now} #{msg}" }
+
+# register multiple effect handlers by passing in a hash
+Affect.on(
+  log: ->(msg) { puts "#{Time.now} #{msg}" },
+  ask: -> { gets.chomp }
+)
+```
+
+`Affect.handle` is used as a catch-all handler:
+
+```ruby
+Affect.handle do |effect, *args|
+  case effect
+  when :log   then puts "#{Time.now} #{msg}"
+  when :ask   then gets.chomp
+  end
+end
+```
+
+Note that when `Affect.handle` is used to handle effects, no error will be
+raised for unhandled effects.
+
+## The effect context
+
+Affect defines an effect context which is unique to *each thread or fiber*.
+Effect contexts can be thought of as stack frames containing information about
+effect handlers. When effects are invoked using method calls on `Affect`, the
+call is routed to the most current effect context. If the current effect context
+does not know how to handle a certain effect, the call will bubble up the stack
+of effect contexts until a handler is found:
+
+```ruby
+# First effect context
+Affect.on(:log) { |msg| LOG.info(msg) },
+).() {
+  log("starting")
+  # Second effect context
+  Affect.on(
+    log: ->(*args) { }
+  ).() {
+    log("this message will not be logged")
+  }
+  log("stopping")
+}
+```
+
+## Putting it all together
+
+The Affect API uses method chaining to add effect handlers and finally, execute
+the application code. Multiple effect handlers can be chained as follows:
+
+```ruby
+Affect
+  .on(:ask) { ... }
+  .on(:tell) { ... }
+  .() do
+    ...
+  end
+```
+
+## Other usages
+
+### Dependency injection
+
+Affect can also be used for dependency injection. Dependencies can be injected
+by providing effect handlers:
+
+```ruby
+Affect.on(:db) {
+  get_db_connection
+}.() {
+  process_users(Affect.db.query('select * from users'))
+}
+```
+
+This is especially useful for testing purposes as described below:
+
+### Testing
+
+One particular benefit of using Affect is the way it facilitates testing. When
+mutable state and side-effects are pulled out of methods and into effect
+handlers, testing becomes much easier. Side effects can be mocked or tested
+in isolation, and dependencies provided through effect handlers can also be
+mocked. The following section includes an example of testing with algebraic
+effects.
+
+## Writing applications using algebraic effects
+
+Algebraic effects have yet to be adopted by any widely used programming
+language, and they remain a largely theoretical subject in computer science.
+Their advantages are still to be proven in actual usage. We might discover that
+they're completely inadequate as a solution for managing side-effects, or we
+might discover new techniques to be used in conjunction with algebraic effects.
+
+One important principle to keep in mind is that in order to make the best of
+algebraic effects, effect handlers need to be pushed to the outside of your
+code. In most cases, the effect context will be defined in the entry-point of
+your program, rather than somewhere on the inside.
+
+Imagine a program that counts the occurences of a user-defined pattern in a
+given text file:
+
+```ruby
+require 'affect'
+
+def pattern_count(pattern)
+  total_count = 0
+  found_count = 0
+  while (line = Affect.gets)
+    total_count += 1
+    found_count += 1 if line =~ pattern
+  end
+  Affect.log "found #{found_count} occurrences in #{total_count} lines"
+  found_count
+end
+
+Affect.on(
+  gets: -> { Kernel.gets },
+  log: -> { |msg| STDERR << "#{Time.now} #{msg}" }
+).() {
+  pattern = /#{ARGV[0]}/
+  count = pattern_count(pattern)
+  puts count
+}
+```
+
+In the above example, the `pattern_count` method, which does the "hard work",
+communicates with the outside world through Affect in order to:
+
+- read a line after line from some input stream
+- log an informational message
+
+Note that `pattern_count` does *not* deal directly with I/O. It does so
+exclusively through Affect. Testing the method would be much simpler:
+
+```ruby
+require 'minitest'
+require 'affect'
+
+class PatternCountTest < Minitest::Test
+  def test_correct_count
+    text = StringIO.new("foo\nbar")
+
+    Affect.on(:gets) { text.gets }.on(:log) { |msg| } # ignore
+    .() {
+      count = pattern_count(/foo/)
+      assert_equal(1, count)
+    }
+  end
+end
+```
+
+## Contributing
+
+Affect is a very small library designed to do very little. If you find it
+compelling, have encountered any problems using it, or have any suggestions for
+improvements, please feel free to contribute issues or pull requests.
+
+## 

data/affect.gemspec

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+require_relative './lib/affect/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'affect'
+  s.version     = Affect::VERSION
+  s.licenses    = ['MIT']
+  s.summary     = 'Affect: Algebraic Effects for Ruby'
+  s.author      = 'Sharon Rosner'
+  s.email       = 'ciconia@gmail.com'
+  s.files       = `git ls-files`.split
+  s.homepage    = 'http://github.com/digital-fabric/affect'
+  s.metadata    = {
+    "source_code_uri" => "https://github.com/digital-fabric/affect"
+  }
+  s.rdoc_options = ["--title", "affect", "--main", "README.md"]
+  s.extra_rdoc_files = ["README.md"]
+  s.require_paths = ["lib"]
+
+  # s.add_runtime_dependency      'modulation',     '~>0.25'
+  
+  s.add_development_dependency  'minitest',       '5.11.3'
+end

data/examples/fact.rb

@@ -0,0 +1,23 @@
+require 'bundler/setup'
+require 'affect'
+
+def fact(x)
+  Affect :log, "calculating factorial for #{x}"
+  (x <= 1) ? 1 : x * fact(x - 1)
+end
+
+def main
+  Affect :prompt
+  x = Affect :input
+  result = fact(x)
+  Affect :output, "The factorial of result is #{result}"
+end
+
+ctx = Affect.on(
+  prompt: -> { puts "Enter a number: " },
+  input:  -> { gets.chomp.to_i },
+  output: ->(msg) { puts msg },
+  log:    ->(msg) { puts "#{Time.now} #{msg}" }
+)
+
+ctx.() { loop { main } }

data/examples/greet.rb

@@ -0,0 +1,16 @@
+require 'bundler/setup'
+require 'affect'
+
+def main
+  Affect :prompt
+  name = Affect :input
+  Affect :output, "Hi, #{name}! I'm Affected Ruby!"
+end
+
+ctx = Affect.on(
+  prompt: -> { puts "Enter your name: " },
+  input:  -> { gets.chomp },
+  output: ->(msg) { puts msg }
+)
+
+ctx.() { main }

data/examples/logging.rb

@@ -0,0 +1,14 @@
+require 'bundler/setup'
+require 'affect'
+
+def mul(x, y)
+  # assume LOG is a global logger object
+  Affect :log, "called with #{x}, #{y}"
+  x * y
+end
+
+Affect.run {
+  puts "Result: #{ mul(2, 3) }"
+}.on(:log) { |message|
+  puts "#{Time.now} #{message} (this is a log message)"
+}.()

data/examples/pat.rb

@@ -0,0 +1,22 @@
+require 'bundler/setup'
+require 'affect'
+
+def pattern_count(pattern)
+  total_count = 0
+  found_count = 0
+  while (line = Affect.gets)
+    total_count += 1
+    found_count += 1 if line =~ pattern
+  end
+  Affect.log "found #{found_count} occurrences in #{total_count} lines"
+  found_count
+end
+
+Affect.on(
+  gets: -> { STDIN.gets },
+  log: ->(msg) { STDERR.puts "#{Time.now} #{msg}" }
+).() {
+  pattern = /#{ARGV[0]}/
+  count = pattern_count(pattern)
+  puts count
+}

data/lib/affect.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# Affect module
+module Affect
+  Abort = Object.new # Used as an abort intent
+
+  # Effect context
+  class Context
+    def initialize(&block)
+      @closure = block
+      @handlers = {}
+    end
+
+    def on(effect, &block)
+      if effect.is_a?(Hash)
+        @handlers.merge!(effect)
+      else
+        @handlers[effect] = block
+      end
+      self
+    end
+
+    def handle(&block)
+      @handlers[nil] = block
+      self
+    end
+
+    def perform(effect, *args)
+      if (handler = find_handler(effect))
+        call_handler(handler, effect, *args)
+      elsif @parent_context
+        @parent_context.perform(effect, *args)
+      else
+        raise "No effect handler for #{effect.inspect}"
+      end
+    end
+
+    def find_handler(effect)
+      @handlers[effect] || @handlers[effect.class] || @handlers[nil]
+    end
+
+    def call_handler(handler, effect, *args)
+      if handler.arity == 0
+        handler.call
+      elsif args.empty?
+        handler.call(effect)
+      else
+        handler.call(*args)
+      end
+    end
+
+    def abort!(value = nil)
+      throw Abort, (value || Abort)
+    end
+
+    def call(&block)
+      current_thread = Thread.current
+      @parent_context = current_thread[:__affect_context__]
+      current_thread[:__affect_context__] = self
+      catch(Abort) do
+        (block || @closure).call
+      end
+    ensure
+      current_thread[:__affect_context__] = @parent_context
+    end
+  end
+
+  class << self
+    def wrap(&block)
+      Context.new(&block)
+    end
+
+    def call(&block)
+      Context.new(&block).call
+    end
+
+    def on(effect, &block)
+      Context.new.on(effect, &block)
+    end
+
+    def handle(&block)
+      Context.new.handle(&block)
+    end
+
+    def current_context
+      Thread.current[:__affect_context__] || (raise 'No effect context present')
+    end
+
+    def perform(effect, *args)
+      current_context.perform(effect, *args)
+    end
+
+    alias_method :method_missing, :perform
+
+    def abort!(value = nil)
+      current_context.abort!(value)
+    end
+  end
+end
+
+# Kernel extension
+module Kernel
+  def Affect(effect, *args)
+    Affect.current_context.perform(effect, *args)
+  end
+end

data/lib/affect/version.rb

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

data/test/test_affect.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+require 'bundler/setup'
+require 'affect'
+
+class AffectAPITest < Minitest::Test
+  def test_that_perform_raises_on_no_handler
+    assert_raises RuntimeError do
+      Affect.wrap {
+        Affect.perform :foo
+      }.on(:bar) {
+        :baz
+      }.()
+    end
+
+    # using method call on Affect
+    assert_raises RuntimeError do
+      Affect.wrap {
+        Affect.foo
+      }.()
+    end
+
+    # no raise
+    Affect.wrap {
+      Affect.perform :foo
+    }.on(:foo) {
+      :bar
+    }.()
+  end
+
+  def test_that_emitted_effect_is_performed
+    counter = 0
+    Affect.wrap {
+      3.times { Affect.perform :incr }
+    }.on(:incr) {
+      counter += 1
+    }.()
+
+    assert_equal(3, counter)
+  end
+
+  def test_that_api_methods_return_context
+    o = Affect.wrap {
+      Affect.perform :foo
+    }
+    assert_kind_of(Affect::Context, o)
+
+    o = Affect.on(:foo) {
+      :bar
+    }
+    assert_kind_of(Affect::Context, o)
+
+    o = Affect.handle { }
+    assert_kind_of(Affect::Context, o)
+  end
+
+  def test_that_contexts_can_be_nested
+    results = []
+    o = Affect.wrap {
+      Affect.perform :foo
+      Affect.perform :bar
+
+      Affect.wrap {
+        Affect.perform :foo
+        Affect.perform :bar
+      }
+      .on(:bar) { results << :baz }
+      .()
+    }
+    .on(:foo) { results << :foo }
+    .on(:bar) { results << :bar }
+    .()
+
+    assert_equal([:foo, :bar, :foo, :baz], results)
+  end
+
+  def test_that_effects_can_be_emitted_as_method_calls_on_Affect
+    results = []
+    o = Affect.wrap {
+      Affect.foo
+      Affect.bar
+
+      Affect.wrap {
+        Affect.foo
+        Affect.bar
+      }
+      .on(:bar) { results << :baz }
+      .()
+    }
+    .on(:foo) { results << :foo }
+    .on(:bar) { results << :bar }
+    .()
+
+    assert_equal([:foo, :bar, :foo, :baz], results)
+  end
+
+  def test_that_abort_can_be_called_from_wrapped_code
+    effects = []
+    Affect.handle { |o| effects << o }.() do
+      Affect 1
+      Affect.abort!
+      Affect 2
+    end
+
+    assert_equal([1], effects)
+  end
+
+  def test_that_abort_causes_call_to_return_optional_value
+    o = Affect.() { Affect.abort! }
+    assert_equal(Affect::Abort, o)
+
+    o = Affect.() { Affect.abort!(42) }
+    assert_equal(42, o)
+  end
+
+  class I1; end
+
+  class I2; end
+
+  def test_that_intent_instances_are_handled_correctly
+    results = []
+    Affect
+      .on(I1) { results << :i1 }
+      .on(I2) { results << :i2 }
+      .() {
+        Affect I1.new
+        Affect I2.new
+    }
+
+    assert_equal([:i1, :i2], results)
+  end
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: affect
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Sharon Rosner
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-07-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 5.11.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 5.11.3
+description: 
+email: ciconia@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- ".gitignore"
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- affect.gemspec
+- examples/fact.rb
+- examples/greet.rb
+- examples/logging.rb
+- examples/pat.rb
+- lib/affect.rb
+- lib/affect/version.rb
+- test/test_affect.rb
+homepage: http://github.com/digital-fabric/affect
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/digital-fabric/affect
+post_install_message: 
+rdoc_options:
+- "--title"
+- affect
+- "--main"
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: 'Affect: Algebraic Effects for Ruby'
+test_files: []