tweed 0.1.0

data/README

@@ -0,0 +1,49 @@
+<!--*-markdown-*-->
+
+# Tweed
+
+Tweed is a small pure-Ruby library for implementing [monads][].
+
+  [monads]: http://en.wikipedia.org/wiki/Monad_%28functional_programming%29
+
+## Examples
+
+    require 'tweed'
+
+### The Maybe Monad
+
+Implementing [the Maybe monad][]:
+
+  [the maybe monad]: http://en.wikipedia.org/wiki/Monad_%28functional_programming%29#Maybe_monad
+
+    class Maybe < Tweed::Monad
+      define_monad do
+        construct { |value, success| @value, @success = value, success }
+        unit { |value| self.new(value, true) }
+        bind { |&block| @success ? block.call(@value) : self }
+        zero { self.new(nil, false) }
+      end
+    end
+
+Using the Maybe monad to implement safe division:
+
+    module SafeDivision
+      def /(other)
+        self.bind do |x|
+          other.bind do |y|
+            y.zero? ? self.class.zero : self.class[x / y]
+          end
+        end
+      end
+    end
+
+And then using the `SafeDivision` module:
+
+    class X < Maybe
+      include SafeDivision
+    end
+    
+    success = X[1] / X[2.0] # => X[0.5]
+    failure = X[1] / X[0]   # => X.zero
+
+This will *not* result in a zero division error.

data/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+ 
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+ 
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+ 
+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 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.
+ 
+For more information, please refer to <http://unlicense.org/>

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/tweed.rb

@@ -0,0 +1,10 @@
+class Object
+  def singleton_class
+    class << self; self; end
+  end
+end
+
+module Tweed
+  autoload :Monad,  'tweed/monad'
+  autoload :Monads, 'tweed/monads'
+end

data/lib/tweed/monad.rb

@@ -0,0 +1,156 @@
+module Tweed
+  ##
+  # Abstract superclass to represent monads.
+  #
+  # To create a monad, subclass and define the monad’s Kleisli triple using
+  # {Monad.define_monad define_monad}.
+  # 
+  # @example Implementing the Maybe monad
+  #   class Maybe < Tweed::Monad
+  #     define_monad do
+  #       # This becomes the `initialize` instance method:
+  #       construct { |value, success| @value, @success = value, success }
+  #       
+  #       # This becomes the `return` class method:
+  #       unit { |value| self.new(value, true) }
+  #       
+  #       # This becomes the `bind` instance method:
+  #       bind { |&block| @success ? block.call(@value) : self }
+  #       
+  #       # This becomes the (cached) `zero` class method:
+  #       zero { self.new(nil, false) }
+  #     end
+  #     
+  #     def inspect
+  #       @success ? "Just #{@value.inspect}" : "Nothing"
+  #     end
+  #   end
+  # 
+  # @example Using the Maybe monad to implement safe division
+  #   class SafeDivision < Maybe
+  #     def /(other)
+  #       self.bind do |x|
+  #         other.bind do |y|
+  #           y.zero? ? self.class.zero : self.class[x / y]
+  #         end
+  #       end
+  #     end
+  #   end
+  #   
+  #   x = SafeDivision[1] / SafeDivision[2.0] # => Just 0.5
+  #   y = SafeDivision[1] / SafeDivision[0]   # => Nothing
+  # 
+  class Monad
+    
+    # Lift a value into this monad. 
+    # @abstract Subclass and override using {Monad.define_monad define_monad}.
+    # @return [Monad] the newly created monad.
+    def self.return(*args)
+      abstract
+    end
+    
+    # Pull an underlying value out of this monad.
+    # @abstract Subclass and override using {Monad.define_monad define_monad}.
+    def bind(&block)
+      abstract
+    end
+    
+    # Syntactic sugar for {Monad.return Monad.return(...)}.
+    # @return [Monad]
+    def self.[](*args)
+      self.return(*args)
+    end
+    
+    ##
+    # Adaptation of `liftM2` from Haskell. ‘Lifts’ a binary function into the
+    # current monad.
+    #
+    # @example Add two numbers
+    #   m_x = SomeMonad[1]
+    #   m_y = SomeMonad[2]
+    #   m_z = m_x.lift_m2(m_y) { |x, y| x + y } # => SomeMonad[1 + 2] => SomeMonad[3]
+    #
+    # @param other another value within the current monad.
+    # @yield [x, y] the underlying values of `self` and `other`.
+    # @return the result of the binary operation, lifted back into the current monad.
+    def lift_m2(other)
+      self.bind do |x|
+        other.bind do |y|
+          self.class[yield(x, y)]
+        end
+      end
+    end
+    
+    protected
+    
+    ##
+    # Class method to set up a Monad subclass using a Kleisli triple.
+    #
+    # Uses a custom DSL to define the triple and an optional monadic zero.
+    #
+    # @example Implementing the List monad
+    #   class List < Tweed::Monad
+    #     define_monad do
+    #       # This becomes the `initialize` instance method, so instance
+    #       # variables will be set on the Monad instance.
+    #       construct { |sequence| @sequence = sequence }
+    #       
+    #       # This becomes the `return` class method, also accessible via `[]`
+    #       # on both the class and instances.
+    #       unit { |value| self.new([value]) }
+    #       
+    #       # This becomes the `bind` instance method, and will always receive
+    #       # a block; it should explicitly use `block.call` instead of `yield`
+    #       # due to the way blocks work in Ruby (Ruby will complain that no
+    #       # block was passed if you `yield`).
+    #       bind { |&block| self.new(@sequence.map(&block).inject(&:+)) }
+    #       
+    #       # The definition of zero for this monad. This will be called once
+    #       # from the class and have its result cached.
+    #       zero { self.new([].freeze!) }
+    #     end
+    #   end
+    #
+    # @see http://en.wikipedia.org/wiki/Monad_(functional_programming)#Concepts
+    #   Wikipedia article on Monads
+    def self.define_monad(&def_block)
+      # Capture the Kleisli triple, and perhaps a monadic zero.
+      capture = Object.new
+      
+      class << capture
+        def construct(&block) @construct = block end
+        def unit(&block)      @unit      = block end
+        def bind(&block)      @bind      = block end
+        def zero(&block)      @zero      = block end
+      end
+      
+      capture.instance_eval(&def_block)
+      
+      class << capture
+        def [](sym) instance_variable_get("@#{sym}".to_sym) end
+      end
+      
+      # Define the necessary methods on the monad, given the components of the
+      # Kleisli triple (and optionally the monadic zero).
+      self.class_eval do
+        define_method(:initialize, &capture[:construct]) unless capture[:construct].nil?
+        define_method(:bind, &capture[:bind]) unless capture[:bind].nil?
+        self.singleton_class.instance_eval do
+          define_method(:return, &capture[:unit]) unless capture[:unit].nil?
+          unless capture[:zero].nil?
+            define_method(:get_zero, &capture[:zero])
+            private(:get_zero)
+            define_method(:zero) { @zero ||= get_zero }
+          end
+        end
+      end
+      
+      self
+    end # def self.define_monad
+  end # class Monad
+end # module Tweed
+
+# @private
+def abstract
+  raise NotImplementedError
+end

data/lib/tweed/monads.rb

@@ -0,0 +1,7 @@
+module Tweed
+  module Monads
+    autoload :Identity, 'tweed/monads/identity'
+    autoload :List,     'tweed/monads/list'
+    autoload :Maybe,    'tweed/monads/maybe'
+  end
+end

data/lib/tweed/monads/identity.rb

@@ -0,0 +1,23 @@
+module Tweed
+  module Monads
+    class Identity < Tweed::Monad
+      define_monad do
+        construct { |value| @value = value }
+        unit { |value| self.new(value) }
+        bind { |&block| block.call(@value) }
+      end
+      
+      def inspect
+        "#{self.class.inspect}[#{@value.inspect}]"
+      end
+      
+      def ==(other)
+        if other.is_a? Identity
+          @value == other.instance_eval { @value }
+        else
+          @value == other
+        end
+      end
+    end # class Identity
+  end # module Monads
+end # module Tweed

data/lib/tweed/monads/list.rb

@@ -0,0 +1,32 @@
+module Tweed
+  module Monads
+    class List < Tweed::Monad
+      define_monad do
+        construct { |sequence| @sequence = sequence }
+        unit { |value| self.new([value]) }
+        bind do |&block|
+          self.class.new(@sequence.map do |item|
+                           block.call(item).to_a
+                         end.inject(&:+))
+        end
+        zero { self.new([].freeze!) }
+      end
+      
+      def +(other)
+        self.class.new(self.to_a + other.to_a)
+      end
+      
+      def inspect
+        "#{self.class.inspect} :: #{@sequence.inspect}"
+      end
+      
+      def to_a
+        @sequence.to_a
+      end
+      
+      def ==(other)
+        self.to_a == other.to_a
+      end
+    end # class List
+  end # module Monads
+end # module Tweed

data/lib/tweed/monads/maybe.rb

@@ -0,0 +1,37 @@
+module Tweed
+  module Monads
+    ## The Maybe monad
+    class Maybe < Tweed::Monad
+      define_monad do
+        construct { |value, success| @value, @success = value, success }
+        unit { |value| self.new(value, true) }
+        bind { |&block| @success ? block.call(@value) : self }
+        zero { self.new(nil, false) }
+      end
+      
+      def inspect
+        repr = @success ? "[#{@value.inspect}]" : ".zero"
+        "#{self.class.inspect}#{repr}"
+      end
+      
+      def ==(other)
+        if other.is_a? Maybe
+          [@value, @success] == other.instance_eval { [@value, @success] }
+        else
+          self.object_id == other.object_id || @value == other
+        end
+      end
+      
+      # An example of safe division implemented over the Maybe monad.
+      module SafeDivision
+        def /(other)
+          self.bind do |x|
+            other.bind do |y|
+              y.zero? ? self.class.zero : self.class[x / y]
+            end
+          end
+        end # def /
+      end # module SafeDivision
+    end # class Maybe
+  end # module Monads
+end # module Tweed

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification 
+name: tweed
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Zachary Voase
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-14 00:00:00 +00:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: yard
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.5.2
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: bluecloth
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.0.5
+    version: 
+description: Tweed is an implementation of monads in Ruby.
+email: zacharyvoase@me.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README
+- UNLICENSE
+- VERSION
+- lib/tweed/monad.rb
+- lib/tweed/monads/identity.rb
+- lib/tweed/monads/list.rb
+- lib/tweed/monads/maybe.rb
+- lib/tweed/monads.rb
+- lib/tweed.rb
+has_rdoc: true
+homepage: http://bitbucket.org/zacharyvoase/tweed
+licenses: 
+- Public Domain
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: An implementation of monads in Ruby.
+test_files: []
+