deterministic 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 59f6546f0d7eb685094458bb948edd79835fcf7e
-  data.tar.gz: 03dee18c4212bd61365220bd755cfd423671eb2e
+  metadata.gz: 925b4c6bf8684358c92969bd99bfaae834ecc96d
+  data.tar.gz: b9e69ef69dbd5fe6e050265d41a39375471b4acc
 SHA512:
-  metadata.gz: d1f1061ada1b36192740b58b3cd38b37af0d822e96f1a4a4473ea8e3c85d66b2f05dedb1456491ab0f63085d5f07d4385934a16b25df948e84021ff3bdbd1d3c
-  data.tar.gz: e5f095fa97070555482469da9a6175c35abacbed7a9ad106ab0d667945daa405931f8c73b8f862845415ecbc74dd7c000c86ae1eb42691791cc4050c8308c3d9
+  metadata.gz: e1d622aec6a69088627ab300883863815e85b7f67b4080072271644aaba31591942f2d23249751047f5d25e850a933414804a59641bb216a3e572a817aebde75
+  data.tar.gz: 9637ca25bc179cfc53464b618e3c8e09332bd3e52085a1c750aaf2715feea65c5ccd701be4cf5388f334f5835007b532ff5f87d8b8edd142592e59bf3656f9a0

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/Guardfile

@@ -0,0 +1,15 @@
+guard :bundler do
+  watch('Gemfile')
+  watch(/^.+\.gemspec/)
+end
+
+guard :rspec do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+  # Turnip features and steps
+  watch(%r{^spec/acceptance/(.+)\.feature$})
+  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$})   { |m| Dir[File.join("**/#{m[1]}.feature")][0] || 'spec/acceptance' }
+end
+

data/README.md

@@ -1,12 +1,12 @@
-# .
+# Deterministic
 
-TODO: Write a gem description
+This is a spiritual successor of the [Monadic gem](http://github.com/pzol/monadic)
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem '.'
+    gem 'deterministic'
 
 And then execute:
 
@@ -14,11 +14,77 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install .
+    $ gem install deterministic
 
 ## Usage
 
-TODO: Write usage instructions here
+### Either#attempt_all
+The basic idea is to execute a chain of units of work and make sure all return either `Success` or `Failure`.
+
+```ruby
+Either.attempt_all do
+  try { 1 }
+  try { |prev| prev + 1 }
+end # => Success(2)
+```
+Take notice, that the result of of unit of work will be passed to the next one. So the result of prepare_somehing will be something in the second try.
+
+If any of the units of work in between fail, the rest will not be executed and the last `Failure` will be returned.
+
+```ruby
+Either.attempt_all do
+  try { 1 }
+  try { raise "error" }
+  try { 2 }
+end # => Failure(RuntimeError("error"))
+```
+
+However, the real fun starts if you use it with your own context. You can use this as a state container (meh!) or to pass a dependency locator:
+
+```ruby
+  class Context
+    attr_accessor :env, :settings
+    def some_service
+    end
+  end
+
+  # exemplary unit of work
+  module LoadSettings
+    def self.call(env)
+      settings = load(env)
+      settings.nil? ? Failure('could not load settings') : Success(settings)
+    end
+
+    def load(env)
+    end
+  end
+
+  Either.attempt_all(context) do
+    # this unit of work explicitly returns success or failure
+    # no exceptions are catched and if they occur, well, they behave as expected
+    # methods from the context can be accessed, the use of self for setters is necessary
+    let { self.settings = LoadSettings.call(env) }
+
+    # with #try all exceptions will be transformed into a Failure
+    try { do_something }
+  end
+```
+
+### Pattern matching
+Now that you have some result, you want to control flow by providing patterns.
+
+```ruby
+Success(1).match do
+  success { |v| "success #{v}"}
+  failure { |v| "failure #{v}"}
+  either  { |v| "either #{v}"}
+end # => "either 1"
+```
+Note: the inner value has been unwrapped! 
+
+Note2: only the last matching pattern block will be executed
+
+The result returned will be the result of the last `#try` or `#let`
 
 ## Contributing
 
@@ -27,3 +93,8 @@ TODO: Write usage instructions here
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+## Inspirations
+ * My [Monadic gem](http://github.com/pzol/monadic) of course
+ * `#attempt_all` was somewhat inspired by [An error monad in Clojure](http://brehaut.net/blog/2011/error_monads)
+ * [Pithyless' rumblings](https://gist.github.com/pithyless/2216519) 

data/deterministic.gemspec

@@ -20,4 +20,9 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "guard"
+  spec.add_development_dependency "guard-bundler"
+  spec.add_development_dependency "guard-rspec"
+  spec.add_development_dependency "simplecov"
 end

data/lib/deterministic/either/attempt_all.rb

@@ -0,0 +1,42 @@
+require 'ostruct'
+module Deterministic::Either
+  def self.attempt_all(context=OpenStruct.new, &block)
+    AttemptAll.new(context, &block).call
+  end
+
+  class AttemptAll
+    class EitherExpectedError < StandardError; end
+    def initialize(context, &block)
+      @context = context || self
+      @tries = []
+      instance_eval(&block)
+    end
+
+    def call(initial=nil)
+      result = @tries.inject(Success(initial)) do |acc, try|
+        acc.success? ? acc.bind(try.call(acc)) : acc
+      end
+    end
+
+    def try(&block)
+      try_p = ->(acc) {
+        begin
+          value = @context.instance_exec(acc.value, &block)
+          Success(value)
+        rescue => ex
+          Failure(ex)
+        end
+      }
+
+      @tries << try_p
+    end
+
+    def let(sym=nil, &block)
+      @tries << ->(acc) { 
+        @context.instance_exec(acc, &block).tap do |value|
+          raise EitherExpectedError unless value.is_a? Either
+        end
+      }
+    end
+  end
+end

data/lib/deterministic/either/failure.rb

@@ -0,0 +1,3 @@
+module Deterministic::Either
+  class Failure < Either; end
+end

data/lib/deterministic/either/match.rb

@@ -0,0 +1,44 @@
+module Deterministic::Either
+  def match(proc=nil, &block)
+    match = Match.new(self)
+    match.instance_eval &(proc || block)
+    match.result
+  end
+
+  class Match
+    def initialize(either)
+      @either     = either
+      @collection = []
+    end
+
+    def success(value=nil, &block)
+      q(:success, value, block)
+    end
+
+    def failure(value=nil, &block)
+      q(:failure, value, block)
+    end
+
+    def either(value=nil, &block)
+      q(:either, value, block)
+    end
+
+    def result
+      matcher = @collection.select { |m| m.first.call(@either.value) }.last
+      matcher.last.call(@either.value)
+    end
+
+  private
+    def q(type, condition, block)
+      if condition.nil?
+        condition_p = ->(v) { true }
+      elsif condition.is_a?(Proc)
+        condition_p = condition
+      else
+        condition_p = ->(v) { condition == @either.value }
+      end
+
+      @collection << [condition_p, block] if @either.is? type
+    end
+  end
+end

data/lib/deterministic/either/success.rb

@@ -0,0 +1,3 @@
+module Deterministic::Either
+  class Success < Either; end
+end

data/lib/deterministic/either.rb

@@ -0,0 +1,58 @@
+module Deterministic::Either
+  def Success(value)
+    Success.unit(value)
+  end
+
+  def Failure(value)
+    Failure.unit(value)
+  end
+
+  class Either
+    def self.unit(value)
+      return value if value.is_a? Either
+      # return Failure.new(value)       if value.nil? || (value.respond_to?(:empty?) && value.empty?) || !value
+      # return Success.new(value)
+      return new(value)
+    end
+
+    def is?(s)
+      const_name = s.slice(0,1).capitalize + s.slice(1..-1)
+      is_a? Module.const_get(const_name)
+    end
+
+    def success?
+      is_a? Success
+    end
+
+    def failure?
+      is_a? Failure
+    end
+
+    def bind(other)
+      return self if failure?
+      return other if other.is_a? Either
+      # return concat(proc) if proc.is_a? Either
+
+      # begin
+      #   Either(call(proc, block))
+      # rescue StandardError => error
+      #   Failure(error)
+      # end
+    end
+
+    # get the underlying value
+    def value
+      @value
+    end
+
+    def ==(other)
+      return false unless other.is_a? self.class
+      @value == other.instance_variable_get(:@value)
+    end
+
+  private
+    def initialize(value) 
+      @value = value
+    end
+  end
+end

data/lib/deterministic/version.rb

@@ -1,3 +1,3 @@
 module Deterministic
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/lib/deterministic.rb

@@ -1,5 +1,9 @@
 require "deterministic/version"
 
-module Deterministic
-  # Your code goes here...
-end
+module Deterministic; end
+
+require 'deterministic/either'
+require 'deterministic/either/match'
+require 'deterministic/either/attempt_all'
+require 'deterministic/either/success'
+require 'deterministic/either/failure'

data/spec/lib/deterministic/attempt_all_spec.rb

@@ -0,0 +1,98 @@
+require 'spec_helper'
+require 'deterministic'
+
+include Deterministic::Either
+include Deterministic
+
+describe Deterministic::Either::AttemptAll do
+  it "#try evaluates the result as Success" do
+    expect(
+      Either.attempt_all do
+        try { @a = 1 }
+        try { @b = @a + 1 }
+      end
+    ).to eq Success(2)
+  end
+
+  it "#try values are passed to the next command" do
+    expect(
+      Either.attempt_all do
+        try { 1 }
+        try { |v| v + 1 }
+      end
+    ).to eq Success(2)
+  end
+
+  it "try treat exceptions as Failure" do
+    attempt = Either.attempt_all do
+      try { 1 }
+      try { raise "error" }
+    end.value
+    expect(attempt).to be_a RuntimeError
+    expect(attempt.message).to eq "error"
+  end
+  
+  it "don't continue on failure" do
+    fake = double()
+    expect(
+      Either.attempt_all do
+        try { 1 }
+        let { Failure(2) }
+        try { fake.should_not_be_called }
+      end
+    ).to eq Failure(2)
+  end
+
+  it "#let expects Success or Failure" do
+    expect(
+      Either.attempt_all do
+        let { Success(1) }
+      end
+    ).to eq Success(1)
+
+    expect {
+      Either.attempt_all do
+        let { 1 }
+      end
+    }.to raise_error(Deterministic::Either::AttemptAll::EitherExpectedError)
+  end
+
+  it "#let will not catch errors" do
+    expect {
+      Either.attempt_all do
+        let { raise "error" }
+      end
+    }.to raise_error
+  end
+
+  it "works with an OpenStruct" do
+    context = OpenStruct.new
+    attempt = Either.attempt_all(context) do
+      let { Success(self.alpha = 2) }
+      try { self.res = 1 }
+    end
+
+    expect(context.res).to eq 1
+    expect(context.alpha).to eq 2
+  end
+
+  it "can operate in the context of a host" do
+    class Host
+      attr_accessor :a
+      def initialize
+        @a = 1
+      end
+    end
+
+    host = Host.new
+
+    expect(
+      Either.attempt_all(host) do
+        try { self.a += 1 }
+        try { self.a + 1 }
+      end
+    ).to eq Success(3)
+
+    expect(host.a).to eq 2
+  end
+end

data/spec/lib/deterministic/either/match_spec.rb

@@ -0,0 +1,54 @@
+require 'spec_helper'
+require 'deterministic'
+
+include Deterministic::Either
+
+describe Deterministic::Either::Match do
+  it "can match Success" do
+    expect(
+      Success(1).match do
+        success { |v| "Success #{v}" }
+        failure { |v| "Failure #{v}" }
+      end
+    ).to eq "Success 1" 
+  end
+
+  it "can match Failure" do
+    expect(
+      Failure(1).match do
+        success { |v| "Success #{v}" }
+        failure { |v| "Failure #{v}" }
+      end
+    ).to eq "Failure 1" 
+  end
+
+  it "can match with values" do
+    expect(
+      Failure(2).match do
+        success    { |v| "not matched s"  }
+        success(1) { |v| "not matched s1" }
+        failure(1) { |v| "not matched f1" }
+        failure(2) { |v| "matched #{v}"   }
+        failure(3) { |v| "not matched f3" }
+      end
+    ).to eq "matched 2"
+  end
+
+  it "can match either" do
+    expect(
+      Failure(2).match do
+        success    { |v| "not matched s"  }
+        either(2)  { |v| "either #{v}"    }
+        failure(3) { |v| "not matched f3" }
+      end
+    ).to eq "either 2"
+  end
+
+  it "can mach with lambdas" do
+    expect(
+      Success(1).match do
+        success ->(v) { v == 1 } { |v| "matched #{v}" }
+      end
+    ).to eq "matched 1"
+  end
+end

data/spec/lib/deterministic/either/success_spec.rb

@@ -0,0 +1,27 @@
+require 'spec_helper'
+require 'deterministic'
+
+include Deterministic::Either
+
+describe Deterministic::Either::Success do
+  subject { described_class.unit(1) }
+
+  specify { expect(subject).to be_an_instance_of described_class }
+  specify { expect(subject.value).to eq 1 }
+  specify { expect(subject).to be_success }
+  specify { expect(subject).not_to be_failure }
+
+  # public constructor #Success[]
+  specify { expect(described_class.unit(1)).to be_an_instance_of described_class }
+  specify { expect(subject).to eq(described_class.unit(1))}
+
+  it "handles chaining using &" do
+    expect(Success(1).bind Success(2)).to eq(Success(2))
+    expect(Success(1).bind Failure(2)).to eq(Failure(2))
+  end
+
+  specify { expect(Success(Success(1))).to eq Success(1) }
+  specify { expect(Success(1).is? :success).to be true }
+  specify { expect(Success(1).is? :either).to  be true  }
+  specify { expect(Success(1).is? :failure).to be false }
+end

data/spec/spec_helper.rb

@@ -0,0 +1,23 @@
+require 'simplecov'
+SimpleCov.start
+
+RSpec.configure do |config|
+  # Limit the spec run to only specs with the focus metadata. If no specs have
+  # the filtering metadata and `run_all_when_everything_filtered = true` then
+  # all specs will run.
+  config.filter_run :focus
+
+  # Run all specs when none match the provided filter. This works well in
+  # conjunction with `config.filter_run :focus`, as it will run the entire
+  # suite when no specs have `:filter` metadata.
+  config.run_all_when_everything_filtered = true
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+  config.order = 'random'
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: deterministic
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Piotr Zolnierek
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-26 00:00:00.000000000 Z
+date: 2013-12-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -38,6 +38,76 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A gem providing failsafe flow
 email:
 - pz@anixe.pl
@@ -46,14 +116,25 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .rspec
 - Gemfile
+- Guardfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - deterministic.gemspec
 - either.rb
 - lib/deterministic.rb
+- lib/deterministic/either.rb
+- lib/deterministic/either/attempt_all.rb
+- lib/deterministic/either/failure.rb
+- lib/deterministic/either/match.rb
+- lib/deterministic/either/success.rb
 - lib/deterministic/version.rb
+- spec/lib/deterministic/attempt_all_spec.rb
+- spec/lib/deterministic/either/match_spec.rb
+- spec/lib/deterministic/either/success_spec.rb
+- spec/spec_helper.rb
 homepage: http://github.com/pzol/deterministic
 licenses:
 - MIT
@@ -78,4 +159,8 @@ rubygems_version: 2.0.14
 signing_key: 
 specification_version: 4
 summary: see above
-test_files: []
+test_files:
+- spec/lib/deterministic/attempt_all_spec.rb
+- spec/lib/deterministic/either/match_spec.rb
+- spec/lib/deterministic/either/success_spec.rb
+- spec/spec_helper.rb