funkr 0.0.23 → 0.0.24

data/README

@@ -0,0 +1,13 @@
+Funkr brings some common functional programming constructs to ruby.
+
+In particular, it offers a simple mechanism to create Algebraïc Data
+Types and do pattern matching on them. For an exemple
+implementation, {Funkr::Types see provided classes}.
+
+It also provide modules for common categories (Monoid, Monad,
+Functor, Applicative ...), and extends common types to support
+categories they belongs to (Array, Hash ...). Categories can also be
+used with custom types, {Funkr::Types see provided classes}.
+
+To get started, we recommand you to read the tests, and get feets wet
+with provided Algebraic Data Types (like Maybe).

data/lib/funkr.rb

@@ -1,8 +1,18 @@
+# -*- coding: utf-8 -*-
 if RUBY_VERSION.split(".")[0..1] == ["1","8"] then
   require 'funkr/compat/1.8'
 end
 
-# Funkr brings some common functional programming constructs to ruby
+# Funkr brings some common functional programming constructs to ruby.
+#
+# In particular, it offers a simple mechanism to create Algebraïc Data
+# Types and do pattern matching on them. For an exemple
+# implementation, {Funkr::Types see provided classes}.
+#
+# It also provide modules for common categories (Monoid, Monad,
+# Functor, Applicative ...), and extends common types to support
+# categories they belongs to (Array, Hash ...). Categories can also be
+# used with custom types, {Funkr::Types see provided classes}.
 module Funkr
-
+  
 end

data/lib/funkr/adt/adt.rb

@@ -6,6 +6,8 @@ module Funkr
   # declare constructors with #adt
   class ADT
 
+    MATCHER = Funkr::Matchers::SafeMatcher
+
     def initialize(const, *data)
       @const, @data = const, data
     end
@@ -25,12 +27,13 @@ module Funkr
     #   on.just{|x| puts x}
     #   on.nothing{ }
     # end
-    def match
-      m = self.class.matcher.new(normal_form)
-      yield m
-      m.run_match
+    def match(&block)
+      self.class.matcher.match_with(normal_form, &block)
     end
-    
+
+    def unsafe_const; @const; end
+    def unsafe_data; @data; end
+
     def to_s
       format("{%s%s%s}",
              @const,
@@ -56,7 +59,7 @@ module Funkr
     end
     
     def self.build_matcher(constructs)
-      @matcher = Class.new(Funkr::Matcher) do
+      @matcher = Class.new(MATCHER) do
         build_matchers(constructs)
       end
     end

data/lib/funkr/adt/matcher.rb

@@ -1,34 +1,45 @@
 module Funkr
+
   # Should not be used directly
-  class Matcher
-    
-    def initialize(match)
-      @const, *@data = match
-      @runner = nil
-      @undefined = self.class.constructs.clone
-    end
-    
-    def self.build_matchers(constructs)
-      @constructs = constructs
-      constructs.each do |c|
-        name, *data = c
-        define_method(name) do |&b|
-          @undefined.delete(name)
-          if @const == name then
-            @runner = b
+  module Matchers
+
+    class SafeMatcher
+      
+      def initialize(match)
+        @const, *@data = match
+        @runner = nil
+        @undefined = self.class.constructs.clone
+      end
+      
+      def self.build_matchers(constructs)
+        @constructs = constructs
+        constructs.each do |c|
+          name, *data = c
+          define_method(name) do |&b|
+            @undefined.delete(name)
+            if @const == name then
+              @runner = b
+            end
           end
         end
       end
-    end
-    
-    def self.constructs; @constructs; end
-    
-    def run_match
-      if @undefined.any? then
-        raise "Incomplete match, missing : #{@undefined.join(" ")}"
+      
+      def self.constructs; @constructs; end
+      
+      def self.match_with(normal_form) # &block
+        m = self.new(normal_form)
+        yield m
+        m.run_match
+      end
+
+      def run_match
+        if @undefined.any? then
+          raise "Incomplete match, missing : #{@undefined.join(" ")}"
+        end
+        @runner.call(*@data)
       end
-      @runner.call(*@data)
+      
     end
-    
+
   end
 end

data/lib/funkr/categories/alternative.rb

@@ -1,7 +1,11 @@
 module Funkr
   module Categories
+    
+    # Functors for which alternative (OR) behaviour can be defined
     module Alternative
       
+      # Provide an alternative. The type must be as follow :
+      #   Functor(A).or_else{ Functor(A) } : Functor(A)
       def or_else
         raise "Alternative#or_else not implemented"
       end

data/lib/funkr/categories/applicative.rb

@@ -1,16 +1,25 @@
+# -*- coding: utf-8 -*-
 module Funkr
   module Categories
+
+    # Functors that can contain a function and be applied to functors
+    # containing parameters for the function
     module Applicative
-      
+
+      # Apply the function living inside the functor . The type must be as follow :
+      #   Functor(λ(A) : B).apply(Functor(A)) : Functor(B)
       def apply
         raise "Applicative#apply not implemented"
       end
 
       module ClassMethods
+        # Curryfy the lambda block, and lift it into the functor
         def curry_lift_proc(&block)
           self.pure(block.curry)
         end
 
+        # Curryfy the lambda block over N parameter, lifting it to
+        # a lambda over N functors
         def full_lift_proc(&block)
           lambda do |*args|
             args.inject(curry_lift_proc(&block)) do |a,e|
@@ -19,6 +28,7 @@ module Funkr
           end
         end
 
+        # Lift the block and call parameters on it.
         def lift_with(*args, &block)
           full_lift_proc(&block).call(*args)
         end

data/lib/funkr/categories/functor.rb

@@ -1,7 +1,12 @@
+# -*- coding: utf-8 -*-
 module Funkr
   module Categories
+    
+    # A functor is a container that can be mapped over
     module Functor
-      
+
+      # Map over the constructor. The type must be as follow :
+      #   Functor(A).map{|A| λ(A) : B} : Functor(B)
       def map
         raise "Functor#map not implemented"
       end

data/lib/funkr/categories/monad.rb

@@ -1,7 +1,21 @@
+# -*- coding: utf-8 -*-
 module Funkr
   module Categories
+    
+    # A functor can also be made an instance of Monad if you can
+    # define a bind operation on it. The bind operation must follow
+    # the monads laws :
+    #  - Functor.unit(x).bind(f) == f.call(X)
+    #  - monad.bind{|x| Functor.unit(x)} == monad
+    #  - monad.bind{|x| f(monad).bind(g)} == monad.bind{|x| f(x)}.bind{|x| g(x)}
+    #
+    # Usually you will want your type to be a monad if you need to
+    # chain functions returning your type, and want to implement
+    # chaining logic once and for all (in bind).
     module Monad
-      
+
+      # Bind operation on monads.  The type must be as follow :
+      # Monad(A).bind{|A| λ(A) : Monad(B)} : Monad(B)
       def bind(&block)
         raise "Monad#bind not implemented"
       end

data/lib/funkr/categories/monoid.rb

@@ -1,7 +1,8 @@
 module Funkr
   module Categories
+    # Monoids are types that can be added and have a zero element.
     module Monoid
-      
+
       def mplus
         raise "Monoid#mplus not implemented"
       end

data/lib/funkr/types/maybe.rb

@@ -1,8 +1,19 @@
+# -*- coding: utf-8 -*-
 require 'funkr/adt/adt'
 require 'funkr/categories'
 
 module Funkr
   module Types
+
+    # Algebraïc Data Type representing the possibility of a missing
+    # value : nothing. It cleanly replace the 'nil' paradigm often
+    # found in ruby code, and often leading to bugs. The Maybe type
+    # belongs to multiple categories, making it extremly expressive to
+    # use (functor, applicative, alternative, monad, monoid ... !).
+    #
+    # You will get maximum performance and maximum expressiveness if
+    # you can use provided high level functions (map, apply, or_else,
+    # ...) instead of pattern-matching yourself.
     class Maybe < ADT
 
       include Funkr::Categories
@@ -13,13 +24,24 @@ module Funkr
 
       include Functor
 
+      # Maybe.nothing.map{|x| something(x)} # => nothing
+      # Maybe.just(x).map{|x| something(x)} # => just something(x)
+      #
+      # {Funkr::Categories::Functor#map see functor map}
       def map(&block)
-        self.match do |on|
-          on.just {|v| self.class.just(yield(v))}
-          on.nothing { self }
-        end
+        # This implementation isn't safe but is a bit faster than the
+        # safe one. A safe implementation would be as follow :
+        # self.match do |on|
+        #   on.just {|v| self.class.just(yield(v))}
+        #   on.nothing { self }
+        # end
+        if self.just? then self.class.just(yield(unsafe_content))
+        else self end
       end
 
+      include Applicative
+      extend Applicative::ClassMethods
+
       # Maybe can be made an applicative functor, for example :
       # f = Maybe.curry_lift_proc{|x,y| x + y}
       # a = Maybe.just(3)
@@ -27,23 +49,28 @@ module Funkr
       # c = Maybe.nothing
       # f.apply(a).apply(b) => Just 7
       # f.apply(a).apply(c) => Nothing
-      include Applicative
-      extend Applicative::ClassMethods
-
+      #
+      # {Funkr::Categories::Applicative#apply see applicative apply}
       def apply(to)
-        self.match do |f_on|
-          f_on.just do |f|
-            to.match do |t_on|
-              t_on.just {|t| self.class.unit(f.call(t)) }
-              t_on.nothing { to }
-            end
-          end
-          f_on.nothing { self }
-        end
+        # This implementation isn't safe but is a bit faster than the
+        # safe one. A safe implementation would be as follow :
+        # self.match do |f_on|
+        #   f_on.just do |f|
+        #     to.match do |t_on|
+        #       t_on.just {|t| self.class.unit(f.call(t)) }
+        #       t_on.nothing { to }
+        #     end
+        #   end
+        # f_on.nothing { self }
+        # end
+        if self.just? and to.just? then
+          self.class.unit(self.unsafe_content.call(to.unsafe_content))
+        else self.class.nothing end
       end
 
       include Alternative
 
+      # {Funkr::Categories::Alternative#or_else see alternative or_else}
       def or_else(&block)
         self.match do |on|
           on.just {|v| self}
@@ -55,6 +82,7 @@ module Funkr
       include Monoid
       extend Monoid::ClassMethods
 
+      # {Funkr::Categories::Monoid#mplus see monoid mplus}
       def mplus(m_y)
         self.match do |x_on|
           x_on.nothing { m_y }
@@ -71,13 +99,24 @@ module Funkr
       include Monad
       extend Monad::ClassMethods
 
+      # {Funkr::Categories::Monad#bind see monad bind}
       def bind(&block)
-        self.match do |on|
-          on.just {|v| yield(v)}
-          on.nothing {self}
-        end
+        # This implementation isn't safe but is a bit faster than the
+        # safe one. A safe implementation would be as follow :
+        # self.match do |on|
+        #   on.just {|v| yield(v)}
+        #   on.nothing {self}
+        # end
+        if self.just? then yield(self.unsafe_content)
+        else self end
       end
 
+      # Unbox a maybe value. You must provide a default in case of
+      # nothing. This method is not as safe as the others, as it will
+      # escape the content from the Maybe type safety.
+      #
+      # Maybe.just(5).unbox(:foobar) # => 5
+      # Maybe.nothing.unbox(:foobar) # => :foobar
       def unbox(default=nil)
         self.match do |on|
           on.just {|v| v }
@@ -91,6 +130,10 @@ module Funkr
         alias mzero nothing
       end
 
+      # unsafe access to content, for performance purpose only
+      def unsafe_content; self.unsafe_data.first; end
+
+      # Box nil as nothing, and the rest as just x
       def self.box(value)
         if value.nil? then self.nothing
         else self.just(value) end

data/lib/funkr/types/simple_record.rb

@@ -1,16 +1,27 @@
 # -*- coding: utf-8 -*-
 module Funkr
   module Types
-    
-    class SimpleRecord < Array
-      ### usage : r = SimpleRecord.new(Hash), then r.field
-      ### r = SimpleRecord.new( name: "Paul", age: 27 )
-      ### r.name => "Paul"  ; r.age => 27
-      ### name, age = r
 
-      ### other usage :
-      ### class Person < SimpleRecord; fields :name, :age; end
-      ### Person.new( name: Paul ) => Error, missing :age
+    # Simple records are a simple way to create records with named AND
+    # positional fields. Records can be updated on a per-field basis
+    # and pattern-matched as arrays. SimpleRecord has the following
+    # advantages above plain Hash :
+    #
+    #  - fields are strict, you can't update an unexisting field by
+    #    mistyping it or by combining it with a different structure
+    #  - you have easy access to fields : named AND positional
+    #
+    # usage : r = SimpleRecord.new(Hash), then r.field
+    # r = SimpleRecord.new( name: "Paul", age: 27 )
+    # r.name # => "Paul"
+    # r.age  # => 27
+    # name, age = r  # => [ "Paul", 27 ]
+    # r.with(age: 29)  # => [ "Paul", 29 ]
+    #
+    # other usage :
+    # class Person < SimpleRecord; fields :name, :age; end
+    # Person.new( name: Paul ) => Error, missing :age
+    class SimpleRecord < Array
 
       class << self; attr_accessor :fields_list; end
       @fields_list = nil
@@ -25,6 +36,8 @@ module Funkr
         end
       end
 
+      # Create a new SimpleRecord. Pass a Hash of keys and associated
+      # values if you want an inline record.
       def initialize(key_vals)
         fields = self.class.fields_list
         if not fields.nil? then # record paramétré
@@ -46,11 +59,13 @@ module Funkr
         end
       end
 
+      # Update a simple record non-destructively
       def with(new_key_vals)
         check_keys(new_key_vals.keys)
         self.class.new(@key_vals.merge(new_key_vals))
       end
 
+      # Update a simple record destructively !!
       def update!(new_key_vals)
         check_keys(new_key_vals.keys)
         @key_vals.merge!(new_key_vals)

data/lib/funkr/version.rb

@@ -1,3 +1,3 @@
 module Funkr
-  VERSION = "0.0.23"
+  VERSION = "0.0.24"
 end

data/test/test_maybe.rb

@@ -28,7 +28,8 @@ class TestMaybe < Test::Unit::TestCase
   def test_or_else
     assert_equal(j(10), n.or_else{j(10)})
     assert_equal(j(4), j(4).or_else{j(2)})
-    # assert_nothing_raised(j(2).or_else{raise 'should not be raised'})
+    assert_nothing_raised{ j(5).or_else{raise 'should not be raised'} }
+    assert_raise(RuntimeError){ n.or_else{raise 'should not be raised'} }
   end
 
   def test_full_lift

metadata

@@ -1,38 +1,51 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: funkr
-version: !ruby/object:Gem::Version
-  version: 0.0.23
-  prerelease: 
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 24
+  version: 0.0.24
 platform: ruby
-authors:
+authors: 
 - Paul Rivier
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-10-21 00:00:00.000000000Z
-dependencies:
-- !ruby/object:Gem::Dependency
+
+date: 2011-12-06 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
   name: rake
-  requirement: &18284740 !ruby/object:Gem::Requirement
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
+    requirements: 
     - - ~>
-      - !ruby/object:Gem::Version
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 9
+        - 2
         version: 0.9.2
   type: :development
-  prerelease: false
-  version_requirements: *18284740
-description: ! '[EXPERIMENTAL] Some functionnal constructs for ruby, like ADT, functors,
-  monads'
-email:
+  version_requirements: *id001
+description: "[EXPERIMENTAL] Some functionnal constructs for ruby, like ADT, functors, monads"
+email: 
 - paul (dot) r (dot) ml (at) gmail (dot) com
 executables: []
+
 extensions: []
+
 extra_rdoc_files: []
-files:
+
+files: 
 - .gitignore
 - .travis.yml
 - Gemfile
+- README
 - Rakefile
 - funkr.gemspec
 - lib/funkr.rb
@@ -61,28 +74,37 @@ files:
 - test/test_hash.rb
 - test/test_maybe.rb
 - test/test_simple_records.rb
+has_rdoc: true
 homepage: http://github.com/paul-r-ml/funkr
 licenses: []
+
 post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
+required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
 requirements: []
+
 rubyforge_project: funkr
-rubygems_version: 1.8.10
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
-summary: ! '[EXPERIMENTAL] Some functionnal constructs for ruby'
+summary: "[EXPERIMENTAL] Some functionnal constructs for ruby"
 test_files: []
+