mon 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a7a736fe71441c3d09d26400d69898a67e4188ca
+  data.tar.gz: d68172fc1348c0d680e9f04f9dd4eeb4369f4f83
+SHA512:
+  metadata.gz: bc9996b5de285ab1f70da5cf4b5ea8ccdb57f917ae1318d02135a050798662b7360fe0abdec5b640e4f4de0b9756d9a08b4fa9c3a72843fb0792d2ed07f45ead
+  data.tar.gz: 647fb1982589a44e407a2d8c4e890d28c8d12ac3eafc7b5ee22acf09e6096ebcd6081ce2ef4a3accebd3af1c698b5b0bc0281f825cadd053490b287c1f5e3451

data/lib/contracts/contract_helpers.rb

@@ -0,0 +1,12 @@
+
+class TrueClass
+  def implies(o)
+    o ? true : false
+  end
+end
+
+class FalseClass
+  def implies(o)
+    true
+  end
+end

data/lib/contracts/future.rb

@@ -0,0 +1,28 @@
+# Contract for the Mon::Future monad, for use with the Contracts gem
+# For example:
+# <tt>Contract C::Future[Num] => C::Future[Num]
+# def futureSquare(l)
+#   l.bind { |i| i * i }
+# end</tt>
+# will work only for (eg) futureSquare(Mon::Future.eventually { wait_for_number_from_thread }).
+# If passed anything (or returning anything) other than a Mon::Future, a
+# ContractViolation will be thrown. <b>Note:</b> since Ruby is dynamically typed,
+# we can't ensure that the eventual value will be of the correct type. So:
+# futureSquare(Mon::Future.eventually { wait_for_string_from_thread }) is likely
+# to succeed (if the thread is still in-flight), and fail when the thread returns.
+# Completed Futures don't have this issue.
+
+module Mon
+  module Contract
+    require_relative 'monad_contract'
+    
+    class Future < MonadContract
+      def valid?(val)
+        # Should be a Future, and if finalized it should satisfy
+        # the provided contract. Note: We can't know if an inflight
+        # contract will satisfy type or not.
+        val.is_a?(Mon::M::Future) and (val.is_a?(Mon::M::FutureComplete).implies(valid_nested_contract?(val._)))
+      end
+    end
+  end
+end

data/lib/contracts/lazy.rb

@@ -0,0 +1,27 @@
+# Contract for the Mon::Lazy monad, for use with the Contracts gem
+# For example:
+# <tt>Contract C::Lazy[Num] => C::Lazy[Num]
+# def lazySquare(l)
+#   l.bind { |i| i * i }
+# end</tt>
+# will work only for (eg) lazySquare(Mon::Lazy.eventually { perform_painful_op_only_if_necessary() }).
+# If passed anything (or returning anything) other than a Mon::Lazy, a
+# ContractViolation will be thrown. <b>Note:</b> since Ruby is dynamically typed,
+# we can't ensure that the eventual value will be of the correct type. So:
+# lazySquare(Mon::Lazy.eventually { op_returning_string }) is likely
+# to succeed, and fail when the operation is actually executed.
+# Finalized Lazy monads don't have this issue.
+
+module Mon
+  module Contract
+    require_relative 'monad_contract'
+    
+    class Lazy < MonadContract
+      def valid?(val)
+        # Should be a Lazy (i.e. pending or final), and if it's
+        # final, the value should be valid re: the provided contract
+        val.is_a?(Mon::M::Lazy) and (val.is_a?(Mon::M::Final).implies(valid_nested_contract?(val._)))
+      end
+    end
+  end
+end

data/lib/contracts/list.rb

@@ -0,0 +1,22 @@
+# Contract for the Mon::List monad, for use with the Contracts gem
+# For example:
+# <tt>Contract C::List[Num] => C::List[Num]
+# def listSquare(l)
+#   l.bind { |i| i * i }
+# end</tt>
+# will work only for listSquare(Mon::List[1, 2, 3, 4]). If passed
+# anything (or returning anything) other than a Mon::List, a
+# ContractViolation will be thrown.
+
+module Mon
+  module Contract
+    require_relative 'monad_contract'
+    
+    class List < MonadContract
+      def valid?(val)
+        # Should be a List whose elements satisfy the given contract
+        val.is_a?(Mon::M::List) and (val._.all? { |el| valid_nested_contract?(el) })
+      end
+    end
+  end
+end

data/lib/contracts/maybe.rb

@@ -0,0 +1,15 @@
+ 
+module Mon
+  module Contract
+    require_relative 'monad_contract'
+    
+    class Maybe < MonadContract
+
+      def valid?(val)
+        # Should either be None or valid?
+        val.is_a?(Mon::M::Maybe) and (val.is_a?(Mon::M::Some).implies(valid_nested_contract?(val._)))
+      end
+
+    end
+  end
+end

data/lib/contracts/monad_contract.rb

@@ -0,0 +1,57 @@
+
+module Mon
+  module Contract
+    require_relative '../mon.rb'
+    require 'contracts'
+
+    class MonadContract < Contracts::CallableClass
+      require_relative 'contract_helpers'
+
+      def initialize(*vals)
+        if vals.length != 1
+          throw ArgumentError.new("Incorrect usage of #{ self.class.name } contract, should be #{ self.class.name }[<contract>]")
+        end
+        @nested_contract = vals[0]
+      end
+
+      def nested_contract
+        @nested_contract
+      end
+
+      def valid?(val)
+        throw RuntimeError.new("MonadContract is abstract, #valid? must be overridden!")
+      end
+
+      def valid_nested_contract?(val)
+        nested_validator = Object::Contract::make_validator(@nested_contract)
+        nested_validator.call(val)
+      end
+
+      def to_s
+        "#{ self.class.name }[#{@nested_contract.to_s}]"
+      end
+    end
+
+    class Monad < MonadContract
+      def valid?(val)
+        return false unless (val.is_a? Mon::M::Monad)
+        case val
+        when Mon::M::List
+          Mon::C::List.new(@nested_contract).valid?(val)
+        when Mon::M::Maybe
+          Mon::C::Maybe.new(@nested_contract).valid?(val)
+        when Mon::M::Try
+          Mon::C::Try.new(@nested_contract).valid?(val)
+        when Mon::M::Lazy
+          Mon::C::Lazy.new(@nested_contract).valid?(val)
+        when Mon::M::Future
+          Mon::C::Future.new(@nested_contract).valid?(val)
+        when Mon::M::React
+          Mon::C::React.new(@nested_contract).valid?(val)
+        else
+          raise RuntimeError.new("Unrecognized monad: #{ val.class }!")
+        end
+      end
+    end
+  end
+end

data/lib/contracts/reactron.rb

@@ -0,0 +1,23 @@
+# Contract for the Mon::React monad, for use with the Contracts gem
+# For example:
+# <tt>Contract C::React[Num] => C::React[Num]
+# def reactSquare(l)
+#   l.bind { |i| i * i }
+# end</tt>
+# will work only for (eg) reactSquare(Mon::React[3]).
+# If passed anything (or returning anything) other than a Mon::React, a
+# ContractViolation will be thrown.
+
+module Mon
+  module Contract
+    require_relative 'monad_contract'
+    
+    class React < MonadContract
+      def valid?(val)
+        # Should be a React (i.e. success or failure), and if it's a 
+        # success, the value should be valid re: the provided contract
+        val.is_a?(Mon::M::React) and (valid_nested_contract?(val._))
+      end
+    end
+  end
+end

data/lib/contracts/try.rb

@@ -0,0 +1,23 @@
+# Contract for the Mon::Try monad, for use with the Contracts gem
+# For example:
+# <tt>Contract C::Try[Num] => C::Try[Num]
+# def trySquare(l)
+#   l.bind { |i| i * i }
+# end</tt>
+# will work only for (eg) trySquare(Mon::Try.to { get_num_from_remote_service() }). If passed
+# anything (or returning anything) other than a Mon::Try, a
+# ContractViolation will be thrown.
+
+module Mon
+  module Contract
+    require_relative 'monad_contract'
+    
+    class Try < MonadContract
+      def valid?(val)
+        # Should be a Try (i.e. success or failure), and if it's a 
+        # success, the value should be valid re: the provided contract
+        val.is_a?(Mon::M::Try) and (val.is_a?(Mon::M::Success).implies(valid_nested_contract?(val._)))
+      end
+    end
+  end
+end

data/lib/mon.rb

@@ -0,0 +1,21 @@
+
+module Mon
+  require_relative 'monads/list'
+  require_relative 'monads/try'
+  require_relative 'monads/maybe'
+  require_relative 'monads/lazy'
+  require_relative 'monads/future'
+  require_relative 'monads/reactron'
+  
+  require_relative 'contracts/list'
+  require_relative 'contracts/try'
+  require_relative 'contracts/maybe'
+  require_relative 'contracts/lazy'
+  require_relative 'contracts/future'
+  require_relative 'contracts/reactron'
+  require_relative 'contracts/monad_contract'
+
+  # Namespace aliases
+  C = Contract
+  M = Monad
+end

data/lib/monads/chainable_monad.rb

@@ -0,0 +1,23 @@
+# Base class for Mon monads. Do not instantiate.
+
+module Mon
+  module Monad
+    module ChainableMonad
+      def method_missing(name, *args, &fun)
+        self.bind { |o| o.send(name, *args, &fun) }
+      end
+
+      def respond_to? name
+        self._canBind?(name)
+      end
+
+      def _
+        self.unwrap
+      end
+
+      def coerce(other)
+        return self, other
+      end
+    end
+  end
+end

data/lib/monads/future.rb

@@ -0,0 +1,154 @@
+# Future wraps an asynchronous process and acts as a placeholder.
+#
+# A simple example:
+# <tt>f = Future.eventually { call_remote_web_service }
+# data = f.bind { |response| response.getContent }
+# while data.pending?
+#   puts "Still waiting..."
+#   sleep 1
+# end
+# puts "Got a response: #{ data.unwrap }" </tt>
+#
+# Rather than explicitly waiting, you can always block on an answer:
+# <tt>data = f.bind { |r| r.getContent }
+# puts "Got a response: #{ data.finalize.unwrap }"</tt>
+
+module Mon
+
+  module Monad
+
+    require_relative 'chainable_monad'
+    require_relative 'monad'
+
+    class Future < Monad
+      include ChainableMonad
+
+      # Create a Future, executing some function, with optional arguments.
+      # Either:
+      # <tt>value = Future::eventually { do_something_slow }</tt>
+      # Or:
+      # <tt>value = Future::eventually(myValue) { |val| do_something_slow(val) }</tt>
+      def self::eventually *args, &fun
+        FuturePromise::perform(fun, args)
+      end
+
+      # Wrap an object in a Future. It will start off as complete, but functions that you bind
+      # to it will be asynchronous.
+      # <tt>value = Future["some_username"]
+      # futureBirthday = value.bind { |username| db.fetchUserInfo(username).getBirthday }  # Returns a FuturePromise, wrapping an inflight thread
+      # puts "We have a birthday for some_username: #{ futureBirthday.unwrap }"</tt>
+      def self::[](obj)
+        FutureComplete[obj]
+      end
+
+      def eql? o
+        # Time to collapse
+        if o.is_a? Future
+          self.unwrap == o.unwrap
+        else
+          self.unwrap == o
+        end
+      end
+
+      def equals? o
+        eql? o
+      end
+
+      def == o
+        eql? o
+      end
+
+      # For use with contracts, DEPRECATED
+      def self::valid?(v)
+        v.is_a?(Mon::Future)
+      end
+
+      class << self
+        protected :new
+      end
+    end
+
+    # FuturePromise represents an asynchronous operation that is still inflight,
+    # or complete.
+    class FuturePromise < Future
+      def initialize(thread)
+        @thread = thread
+      end
+      
+      # Equivalent to calling Future::eventually { ... }
+      def self::perform(fun, args)
+        if args.length == 1 and args[0].is_a? FuturePromise
+          # We're waiting on something, but we don't want to block
+          FuturePromise.new(Thread.new { fun.call(args[0].unwrap) })
+        else
+          FuturePromise.new(Thread.new(args) { |args| fun.call(*args) })
+        end
+      end
+
+      # Take a block, and apply it to the value asynchronously, returing
+      # a future to represent the result
+      def bind &fun
+        FuturePromise::perform(fun, [self])
+      end
+
+      # Block, then return the result (unwrapped)
+      def unwrap
+        @thread.value
+      end
+
+      # Block until the operation completes, then return the result (wrapped as a FutureComplete)
+      def finalize
+        value = @thread.value
+        FutureComplete[(value.is_a? Future) ? value.unwrap : value]
+      end
+
+      # Are we still inflight?
+      def pending?
+        @thread.alive?
+      end
+
+      def to_s
+        "FuturePromise[#{ @thread }]"
+      end
+
+      class << self
+        protected :new
+      end
+    end
+
+    # FutureComplete represents a finalized value.
+    class FutureComplete < Future
+      def initialize(value)
+        @value = value
+      end
+
+      # You should probably be using Future[...] instead.
+      def self::[](value)
+        self::new(value)
+      end
+
+      # Asyrchronously apply fun to the value wrapped by this FutureComplete. Returns a FuturePromise.
+      def bind &fun
+        FuturePromise::perform(fun, [@value])
+      end
+
+      def pending?
+        false
+      end
+
+      def unwrap
+        @value
+      end
+
+      def to_s
+        "FutureComplete[#{ @value }]"
+      end
+
+      class << self
+        protected :new
+      end
+    end
+
+  end
+
+end

data/lib/monads/lazy.rb

@@ -0,0 +1,200 @@
+# Lazy wraps computations which will only be performed on-demand.
+#
+# A simple example:
+# <tt>l = Lazy.eventually(n) { perform_some_slow_operation(n) }
+# data = f.bind { |result| some_even_more_costly_operation(result) }
+# # At this point, no real computation has taken place
+# puts "Here's the result: #{ data.unwrap } # ouch!</tt>
+#
+# Why would you ever want to do this? Here's an example:
+# <tt>factNums = (0..100000).map { |i| Lazy[i] }.map { |m| m.bind { |i| i.factorial } }
+# # We now have a list of 100000 'potential' factorial numbers, but
+# # we've done this very quickly: we haven't actually done any math yet.
+# fiveThousandFact = factNums[5000].unwrap
+# # We've performed exactly one factorial operation! And yet we can pass around
+# # and use factNums as if it really was a list of factorials. Neat!</tt>
+
+module Mon
+
+  module Monad
+
+    require_relative 'chainable_monad'
+    require_relative 'monad'
+
+    # Lazy is the parent class of Pending and Final, the two states a Lazy monad can be in.
+    # Use with:
+    # <tt>lazyValue = Lazy[5] # Seems pointless so far...
+    # lazyCalc = lazyValue.bind { |i| (0..i).map { |n| n.factorial } }.bind { |factlist| factlist.map { |i| i * i }.... # Keep right on going!
+    # # We still haven't done any work!
+    # puts lazyCalc.unwrap # Time to have a nap...</tt>
+    # Or:
+    # lazyProc = Lazy.eventually(5) { (0..5).map { |i| call_some_remote_service_ondemand(i) } }
+    # # Haven't done anything yet...
+    # lazyProc.sample.unwrap.map { |v| "A random response: #{ v }" } # Do one of 5 possible service calls</tt>
+    class Lazy < Monad
+      include ChainableMonad
+
+      # Wrap a value in Lazy
+      def self::[](obj = nil)
+        if obj.is_a? Proc
+          eventually(obj)
+        else
+          Final[obj]
+        end
+      end
+
+      # Perform an operation, if necessary:
+      # <tt>Lazy.eventually { 10 * 10 }</tt>
+      # Or:
+      # <tt>Lazy.eventually(10) { |n| n * 10 }</tt>
+      def self::eventually(*args, &fun)
+        Pending::eventually(fun, args)
+      end
+
+      # For contracts. Deprecated!
+      def self::valid?(v)
+        v.is_a? Mon::Lazy
+      end
+
+      class << self
+        protected :new
+      end
+    end
+
+    # Final represents a finalized lazy value (i.e. a value with no pending ops).
+    class Final < Lazy
+      def initialize(obj)
+        @obj = obj
+      end
+
+      # You probably want Lazy[...]
+      def self::[](obj = nil)
+        Final.new(obj)
+      end
+
+      # Add an operation to be performed on the wrapped value, only if necessary
+      def bind(&fun)
+        Pending::eventually(fun, [@obj])
+      end
+
+      # Perform any pending lazy operations
+      def finalize
+        self
+      end
+
+      def _canBind?(name)
+        @obj.respond_to? name
+      end
+
+      def _finalized?
+        true
+      end
+
+      # Perform any pending lazy operations and unwrap the result
+      def unwrap
+        @obj
+      end
+
+      # Alias for #unwrap
+      def _
+        unwrap
+      end
+
+      def to_s
+        "Final[#{ @obj }]"
+      end
+
+      def eql? o
+        # Time to collapse
+        if o.is_a? Lazy
+          self.unwrap == o.unwrap
+        else
+          self.unwrap == o
+        end
+      end
+
+      def equals? o
+        eql? o
+      end
+
+      def == o
+        eql? o
+      end
+
+      class << self
+        protected :new
+      end
+    end
+
+    # Pending represents a Lazy value with pending operations. Unwrapping or finalizing with trigger
+    # said pending operations.
+    class Pending < Lazy
+      def initialize(fun, target = nil)
+        case fun.arity
+        when 1 then @fun = lambda { fun.call(target.unwrap) }
+        when 0 then @fun = fun
+        else raise ArgumentError.new("Bad function passed to #{ self }")
+        end
+      end
+
+      # Add an operation to be performed on the wrapped value, only if necessary
+      def bind(&fun)
+        Pending::eventually(fun, [self])
+      end
+
+      def _canBind?(name)
+        true
+      end
+
+      # Complete any pending operations and return the result, wrapped in a Final.
+      # Eg: <tt>Lazy(10).bind { |i| i * i }.finalize # ==> Final[100]</tt>
+      def finalize
+        Final[unwrap]
+      end
+
+      # Complete any pending operations and return the result, unwrapped.
+      # Eg: <tt>Lazy(10).bind { |i| i * i }.unwrap # ==> 100</tt>
+      def unwrap
+        @fun.call
+      end
+
+      # Alias for #unwrap
+      def _
+        unwrap
+      end
+
+      # Perform an operation, if necessary:
+      # <tt>Lazy.eventually { 10 * 10 }</tt>
+      # Or:
+      # <tt>Lazy.eventually(10) { |n| n * 10 }</tt>    
+      def self::eventually fun, args
+        Pending.new(lambda { fun.call(*args.map { |v| (v.is_a? Lazy) ? v.unwrap : v }) })
+      end
+
+      def to_s
+        "Pending[#{ @fun }]"
+      end
+
+      def eql? o
+        # Time to collapse
+        if o.is_a? Lazy
+          self.unwrap == o.unwrap
+        else
+          self.unwrap == o
+        end
+      end
+
+      def equals? o
+        eql? o
+      end
+
+      def == o
+        eql? o
+      end
+
+      class << self
+        protected :new
+      end
+    end
+  end
+end