consequence 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3038f8d2f6c5083a3e945054dd080b655507ae47
-  data.tar.gz: 16ec4fc46d518cadd43564e87acb3bca08e4c8c6
+  metadata.gz: 2213b692e96e63757d2f58234f110e448be7a1ef
+  data.tar.gz: 38ddbf1267f4e1d68d5d3e87e1967a7aeef4ff9d
 SHA512:
-  metadata.gz: fdf17369f753147abb4d225f9690e6206235f506d82a346987aee3c8b89f97084592a524d6a9ef6f2d9506936553793707987104d6d1f6b1df4df543483530d6
-  data.tar.gz: f79925766a50f40b0d63e62cc5dc5f39e4d53d48ea60a85161dabc292f247562eecb682a483cb0a39e1479f0fcf6aa3ad139d0698ac7f00bef03a188549d64dd
+  metadata.gz: da489d84fb8b756fa681a34f9fcade73d7af4b1aace229b95ad627d1682484ebdfd52d95948df7ccec6356273c294c03712718cd019320200f19fa477bb16f63
+  data.tar.gz: 3a3d53e75a35fb4baf47acf9723713edb91f9618a4d6664e0408b2e9065ee191e1c76fd5c01f12c13aa4018e09f0b65b9636d35ba64df5f118ef7df607b17867

data/README.md

@@ -6,121 +6,213 @@ Simple monad implementation with clear and consistent syntax.
 
 ## Usage
 
+A monad has a value that it is wrapped around. Its value can be anything: String, Module, Proc etc...
+It takes its value as its only argument and can be initialized using the element reference syntax:
+
 ``` ruby
 require 'consequence'
+include Consequence
 
-def process(i)
-  Foo[i] >> :next << log >> validate
-end
+my_monad = Monad[4]
+```
 
-def log
-  ->(v) { puts v }
-end
+Its value can be retrieved with the `#value` getter method.
 
-def validate
-  ->(v, m) { m == Foo[5] ? m : Bar['Fail'] }
-end
+``` ruby
+my_monad.value # 4
+```
 
-Foo = Class.new(Consequence::Monad)
-Bar = Class.new(Consequence::Monad)
+To create new monad types, simply inherit from `Monad`.
 
-p process(0) # Bar['Fail']
-p process(4) # Foo[5]
+``` ruby
+Foo = Class.new(Monad)
+Bar = Class.new(Monad)
 ```
 
-## Operations
+A monad is equal to another monad only if both it's type and value are equal.
 
-<dl>
-  <dt> &gt;&gt; Right Shift </dt>
-  <dd>Chains a proc with the result being passed along. If the result is not a monad, it is wrapped up in one.</dd>
+``` ruby
+Foo[0] == Foo[1] # false
+Foo[0] == Bar[0] # false
+Foo[0] == Foo[0] # true
+```
 
-  <dt> &lt;&lt; Left Shift </dt>
-  <dd>The supplied proc is applied with the result being ignored and the unchanged monad is passed down the chain.</dd>
-</dl>
+### Operations
 
-If the proc accepts one argument, it is passed only the `value` of the monad. If it accepts two arguments, it is passed both the `value` and the monad.
+Monads have two main operations `>>` and `<<`.
 
-Before being called, the proc have their `#to_proc` method called. This allows a `Symbol` to be passed in, whose `#to_proc` method sends the symbol as a message to the `value` of the monad.
+Both take a proc for their only argument. The supplied proc can take 0-2 arguments and the monad will match them, even if it's a lamda or method object with arity checking.
 
-## Types
+It's first argument will be passed the monads value:
 
-### Success & Failure
+``` ruby
+Foo[4] << ->(v) { puts v }
+# $ 4
+```
 
-A `Success` monad wraps up all exceptions in a `Failed` monad and a `Failed` monad ignores all chained methods. This allows all possible failures in a long process to be dealt with at the end.
+It's second argument will be passed the monad itself. This is useful for making decisions based on the monads type.
 
 ``` ruby
-require 'consequence'
+Foo[0] << ->(v, m) { puts v if m.is_a?(Foo) }
+# $ 0
+```
+
+### `>>`
+
+The `>>` operation may be variously thought of as the 'map', 'bind' or 'join' operations, but has been left unnamed to avoid any specific connotations.
+
+It takes the result of the proc given to it and passes it on:
+
+``` ruby
+Foo[0] >> ->(v) { Bar[v] } # Bar[0]
+```
+
+If it return's a result that is not a monad, it is wrapped up in one so the chain can continue:
+
+``` ruby
+Foo[0] >> ->(v) { v + 1 } # Foo[1]
+```
+
+### `<<`
+
+The `<<` operation may be thought of as the 'pipe' operation.
+
+It calls the proc given to it, but ignores it's return value:
+
+``` ruby
+Foo[0] << ->(v) { v + 1 } # Foo[0]
+```
+
+This is useful for creating 'side effects', such as logging or assigning instance variables:
+
+``` ruby
+Foo[0] << ->(v) { @side_effect = v + 1 } # Foo[0]
+puts @side_effect
+# $ 1
+```
 
-module CreateUser
-  class << self
-    include Consequence
-    alias_method :m, :method
+### `#to_proc`
 
-    def create(attributes)
-      Success[attributes] >> m(:build) >> m(:validate) >> m(:persist)
-    end
+Before either operation calls a proc, the `#to_proc` method is called on it. This can be useful if the operation is given an object that is no a proc, but has a `#to_proc` method that returns one.
 
-    private
+A good example of this is the Symbol object, whose `#to_proc` method supplies a proc that sends the symbol as a message to its first argument. In this case this means calling that method on the value:
 
-    def build(attributes)
-      User.new(attributes)
-    end
+``` ruby
+Foo[[1, 4, 7]] >> :pop # Foo[7]
+```
 
-    def validate(user)
-      validator = UserValidator.new(user)
-      validator.valid? ? Success[user] : Failure[validator.errors]
-    end
+This also can be used to make a composition syntax, by writing a `#to_proc` method for a monad:
 
-    def persist(user)
-      user.save
-    end
+``` ruby
+class Add < Monad
+  def to_proc
+    ->(v) { v + value }
   end
 end
+
+Add[1] >> Add[4] >> Add[6] # Add[11]
 ```
 
-If the `User#new` raises an exception, the `validate` and `persist` methods won't be called, and a `Failure` monad will be returned with the exception as it's `value`.
+## Built-In Types
 
-If the `validator` finds the new user to be invalid, the `persist` method will not be called and a `Failure` monad will be returned with the errors as it's `value`.
+### NullMonad
 
-### Something & Nothing
+The `NullMonad` is a monad whose `>>` and `<<` operations have been overriden to ignore all input:
+
+``` ruby
+NullMonad[0] >> ->(v) { v + 1 } # Consequence::NullMonad[0]
+```
 
-A `Something` monad wraps up a nil result in a `Nothing` monad and a `Nothing` monad ignores all chained methods. This prevents `MissingMethod` errors from trying to be call a method on `nil`.
+This is different from the `<<` operation, because the proc isn't even run, so can cause no side effects:
 
-## Utils
+``` ruby
+NullMonad[0] << ->(v) { @side_effect = v + 1 }
+puts @side_effect.inspect
+# $ nil
+```
+
+For both operations, the `NullMonad` returns itself, so a chain of operations can be called on it without causing an error. This can be useful for stoping a chain midway through safely:
+
+``` ruby
+Continue = Class.new(Monad)
+Stop = Class.new(NullMonad)
+
+drop_first = ->(v) { v[1..-1] }
+check_empty = ->(v, m) { v.empty? ? Stop[v] : m }
+
+Continue[[1, 3, 4]] >> drop_first >> check_empty >> # Continue[[3, 4]]
+                       drop_first >> check_empty >> # Continue[[4]]
+                       drop_first >> check_empty >> # Stop[[]]
+                       drop_first >> check_empty    # Stop[[]]
+```
 
-### `send_to_value` and `send_to_monad`
+### Success & Failure
 
-`send_to_value` and `send_to_monad` are utility methods that can be included from `Consequence::Utils`. They create procs that pass their arguments to the send method on the value and monad respectively.
+A `Success` monad wraps up all exceptions in a `Failure` monad:
 
 ``` ruby
-include Consequence::Utils
+Success[0] >> ->(v) { 5 / v }
+# Consequence::Failure[#<ZeroDivisionError: divided by 0>]
+```
+
+A `Failure` monad is a subclass of the `NullMonad` so all successive chained procs are ignored.
 
-Monad[2] << send_to_value(:**, 3) # Monad[8]
+Both `Success` and `Failure` respond to the `#succeeded?` and `#failed?` query methods in the way you'd expect:
+
+``` ruby
+Success[0].succeeded? # true
+Success[0].failed? # false
+Failure[0].succeeded? # false
+Failure[0].failed? # true
 ```
 
-To include into Object to be available within all objects:
+For an example, check out the [Success & Failure example](https://github.com/mushishi78/consequence/wiki/Success-&-Failure-Example) on the wiki.
+
+### Something & Nothing
+
+A `Something` monad wraps up a nil result in a `Nothing` monad:
 
 ``` ruby
-require 'consequence/core_ext/utils'
+Something[[1, 3, 5]] >> ->(v) { v[4] } # Consequence::Nothing[nil]
 ```
 
-### `Object#m`
+A `Nothing` monad is also a subclass of the `NullMonad` so all successive chained procs are ignored. This prevents `MissingMethod` errors from trying to call a method on a `nil`.
 
-As a shorthand for the `Object#method` method, it can be useful to alias this to m, such as in the Success/Failure example. To do this for all objects:
+A `Nothing` responds positively to the `#nil?` method:
 
 ``` ruby
-require 'consequence/core_ext/m_alias'
+Nothing[nil].nil? # true
 ```
 
-### `Symbol#to_proc`
+## DelegatesToValue
 
-`Symbol#to_proc` can't be used to call private methods. This is inconvenient if you want an object to wrap itself up and call it's oen private methods with symbols. To use that style of notation, you can add this:
+`DelegatesToValue` is a module that can be included into Monad that adds a `#method_missing` method to delegate calls to its value:
 
 ``` ruby
-require 'consequence/core_ext/private_symbol_proc'
+Foo.include DelegatesToValue
+Foo[[1, 4, 6]].map {|n| n + 1} # Foo[[2, 5, 7]]
 ```
 
-Alternatively, you can use `object#method`.
+It delegates via the `>>` operation, so subclasses of the NullMonad will respond to delegated method calls, but still take no action:
+
+``` ruby
+Something.include DelegatesToValue
+Nothing.include DelegatesToValue
+
+dangrous_hash = {user: {orders: {1 => {price: 3.99} } } }
+
+Something[dangrous_hash][:user][:orders][1][:price] # Consequence::Something[3.99]
+Something[dangrous_hash][:user][:orders][2][:price] # Consequence::Nothing[nil]
+```
+
+## Wiki
+
+To find some examples and information about utils, [check out the wiki](https://github.com/mushishi78/consequence/wiki/Consequence) and feel free to contribute to it.
+
+## Inspirations
+
+* [Deterministic](https://github.com/pzol/deterministic)
+* [Kleisli](https://github.com/txus/kleisli)
 
 ## Installation
 

data/lib/consequence.rb

@@ -2,6 +2,7 @@ module Consequence
 end
 
 require 'consequence/monad'
-require 'consequence/utils'
 require 'consequence/success'
 require 'consequence/something'
+require 'consequence/delegates_to_value'
+require 'consequence/utils'

data/lib/consequence/delegates_to_value.rb

@@ -0,0 +1,16 @@
+require 'consequence/monad'
+
+module Consequence
+  module DelegatesToValue
+    def method_missing(method_name, *args, &b)
+      return super unless value.respond_to?(method_name)
+      self >> -> { value.send(method_name, *args, &b) }
+    end
+
+    protected
+
+    def respond_to_missing?(method_name, include_private = false)
+      value.respond_to?(method_name, include_private) || super
+    end
+  end
+end

data/lib/consequence/utils.rb

@@ -1,5 +1,7 @@
 module Consequence
   module Utils
+  	alias_method :m, :method
+
     def send_to_value(*args)
       ->(v) { v.send(*args) }
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: consequence
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Max White
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-15 00:00:00.000000000 Z
+date: 2015-01-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -39,9 +39,8 @@ files:
 - LICENSE.txt
 - README.md
 - lib/consequence.rb
-- lib/consequence/core_ext/m_alias.rb
-- lib/consequence/core_ext/private_symbol_proc.rb
 - lib/consequence/core_ext/utils.rb
+- lib/consequence/delegates_to_value.rb
 - lib/consequence/monad.rb
 - lib/consequence/something.rb
 - lib/consequence/success.rb

data/lib/consequence/core_ext/m_alias.rb

@@ -1,3 +0,0 @@
-class Object
-  alias_method :m, :method
-end

data/lib/consequence/core_ext/private_symbol_proc.rb

@@ -1,9 +0,0 @@
-# This allows symbol#to_proc method to call private functions.
-# Which can be useful if you want to have a class wrap itself in
-# a Monad and call it private methods.
-
-class Symbol
-  def to_proc
-    ->(v) { v.send(self) }
-  end
-end