fmap 0.0.1

data/LICENSE

@@ -0,0 +1,9 @@
+Copyright (c) 2011 Sean Keith McAuley
+
+This software is MIT-licensed.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.

data/README.md

@@ -0,0 +1,75 @@
+# About
+
+The `fmap` library defines three methods on all object instances, `Object#fmap`, `Object#afmap`, and `Object#eqfmap`. All three methods are ways to "descend into" arbitrarily-nested data structures to an arbitrary depth, replacing each object in the structure with the return value of the supplied block. This makes these methods a generalization of `Enumerable#map`, that, instead of applying to all Enumerable objects, apply to all *functors*.
+
+From the perspective of the `fmap` library, a *functor* is anything that has a `#functor?` method which returns true. This, by default, includes all built-in container objects, such as Array, Hash, Range, and Set, and also anything which imports the `Enumerable` module (where `Enumerable#fmap` is defined in terms of `Enumerable#map`.) It also includes `Object::Composite`, a module that is brought in by the `fmap` library which you can import to make any simple data structure class (where "simple" means that every instance variable is an exposed value of the container) `fmap`pable.
+
+# Usage
+
+`Object#fmap` is the most general method; it will simply yield every object in the data structure. However, this means that `Object#fmap` also yield the data structure itself. If you don't want this behavior, use `Object#afmap`, which will only yield "atomic" (non-*functor*) values. A comparison:
+
+    require 'fmap'
+    require 'set'
+    
+    stuff = Set[{[1, 2, 3] => [4, 5, 6, true]}, -3.5, :hmm]
+    
+    stuff.afmap{ |v| v.inspect } # => #<Set: {{["1", "2", "3"]=>["4", "5", "6", "true"]}, "-3.5", ":hmm"}>
+    
+    stuff.fmap{ |v| v.inspect } # => "#<Set: {\"{\\\"[\\\\\\\"1\\\\\\\", \\\\\\\"2\\\\\\\", \\\\\\\"3\\\\\\\"]\\\"=>\\\"[\\\\\\\"4\\\\\\\", \\\\\\\"5\\\\\\\", \\\\\\\"6\\\\\\\", \\\\\\\"true\\\\\\\"]\\\"}\", \"-3.5\", \":hmm\"}>"
+    
+The trivial use of `Object#fmap`, using the identity combinator (`id = lambda{ |v| v }`), produces a deep copy without using serialization:
+
+    require 'fmap'
+
+    stuff = Set[{[1, 2, 3] => [4, 5, 6, true]}, -3.5, :hmm]
+    new_stuff = stuff.fmap{ |v| v }
+
+`Object#eqfmap` takes a type object as an argument. The type object is used in an equivalence-class comparison (`Object#===`) to determine whether to yield each value.
+
+    require 'fmap'
+
+    stuff = Set[{[-1, 2, 3] => [4, :x, 82, 6, true]}, -3.5, :hmm]
+    stuff_without_symbols = stuff.eqfmap(Symbol){ |v| v.to_s }
+    stuff_without_symbols # => #<Set: {{[-1, 2, 3]=>[4, "x", 82, 6, true]}, -3.5, "hmm"}>
+
+    ranged_stuff = stuff.eqfmap(Numeric){ |v| [[v, 0].max, 50].min }
+    ranged_stuff # => #<Set: {{[0, 2, 3]=>[4, "x", 50, 6, true]}, 0, "hmm"}>
+
+
+# Using `fmap` with your own data structures
+
+You can add `fmap` support to your own data structures in three ways:
+
+1. You can simply make your class `Enumerable`. When `Object#fmap` is called on your class's instances, they will be iterated through using `Enumerable#map`, and the result will be an Array.
+
+2. You can include the module `Object::Composite` in your class. For each object of this type, a shallow clone will be made of it; then each instance variable set on the instance will be read, `fmap`ped itself, yielded, and then overwritten with the yielded value. This is very likely inefficient in most implementations.
+
+3. You can define your own `#fmap` and `#functor?` methods. (`Object#afmap` and `Object#eqfmap` are both defined in terms of `Object#fmap`.)
+
+An `#fmap`-supporting class looks like this:
+
+    class Foo
+      def initialize(a, b)
+        @attr_a = a
+        @attr_b = b
+      end
+
+      ...
+    
+      def functor?
+        true
+      end
+      
+      def fmap(&bl)
+        new_attr_a  = @attr_a.fmap(&bl)
+        new_attr_b  = @attr_b.fmap(&bl)
+        new_inst = self.class.new(new_attr_a, new_attr_b)
+        bl.call( new_inst )
+      end
+    end
+
+There are three parts to the `#fmap` definition:
+
+1. Call `#fmap` on your own values, passing on the block passed to you.
+2. Create a new instance of yourself with the results of those `#fmap` calls as the new data.
+3. Finally, yield that new instance to the block, and return the value returned from the block.

data/lib/fmap.rb

@@ -0,0 +1,72 @@
+class Object
+  module Composite
+    def fmap(&bl)
+      begin
+        new_inst = self.clone
+      rescue TypeError
+        return self
+      end
+
+      new_inst.instance_variables.each do |iv_name|
+        iv_val = new_inst.instance_variable_get(iv_name)
+        fmapped_val = bl.call( iv_val.fmap(&bl) )
+        new_inst.instance_variable_set(iv_name, fmapped_val)
+      end
+    end
+    
+    def functor?
+      true
+    end
+  end
+
+  def functor?
+    false
+  end
+
+  def fmap
+    yield( self )
+  end
+
+  def afmap
+    self.fmap{ |v| v.functor? ? v : yield(v) }
+  end
+  
+  def eqfmap(type)
+    self.fmap{ |v| (type === v) ? yield(v) : v }
+  end
+end
+
+module Enumerable
+  def functor?
+    true
+  end
+  
+  def fmap(&bl)
+    bl.call( self.map{ |v| v.fmap(&bl) } )
+  end
+end
+
+class Range
+  def fmap(&bl)
+    bl.call( self.class.new(
+      self.first.fmap(&bl),
+      self.last.fmap(&bl),
+      self.exclude_end?) )
+  end
+end
+
+class Hash
+  def fmap(&bl)
+    new_h = self.class.new
+    self.each do |k, v|
+      new_h[k.fmap(&bl)] = v.fmap(&bl)
+    end
+    bl.call( new_h )
+  end
+end
+
+class Set
+  def fmap(&bl)
+    bl.call( self.map{ |v| v.fmap(&bl) }.to_set )
+  end
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: fmap
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Sean Keith McAuley
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-08-22 00:00:00.000000000Z
+dependencies: []
+description: fmap provides a "deep map" method that maps over any mix of arbitrarily-nested
+  data-structures
+email: sean@zarokeanpie.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- LICENSE
+- lib/fmap.rb
+homepage: http://github.com/derefr/fmap
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.8
+signing_key: 
+specification_version: 3
+summary: fmap provides a "deep map" method that maps over any mix of arbitrarily-nested
+  data-structures
+test_files: []