facets 1.7.38 → 1.7.46

data/README

@@ -6,12 +6,23 @@
 
 == Introduction
 
-Ruby Facets is the a collection of general purpose, pure-Ruby extensions and additions for the Ruby programming language. Facets is divided into two libraries, one for the extensions and the other for the additions. called Facets/CORE and Facets/MORE, respectively.
-
-Facets/CORE is a large collection of methods which extend the core capabilities of Ruby's built-in classes and modules. This collection of extension methods are unique by virtue of their atomicity. The methods are stored individually so that each can be required independently. This gives developers fine-grain control over which  extra methods to bring into his or her code. The collection currently contains over 400 methods spanning 28 classes and modules. It is an _atomic_ library in that the methods are packaged individually so that each can be _required_ independently. This gives the programmer greater 
-control to include only the extra methods he or she actually needs.
-
-Facets/MORE are a collection of classes, modules and light frameworks whcih consitutes an ever growing and improving source of reusable components. Some very nice additions are provided, from an amazing SI Units system to an elegant Annotations system. And of course there are all the more typical goodies like Tuple, Functor and Multiton.
+Ruby Facets is a collection of general purpose, pure-Ruby extensions and additions
+for the Ruby programming language. Facets is divided into two libraries, one for the
+extensions and the other for the additions. called Facets/CORE and Facets/MORE, respectively.
+
+Facets/CORE is a large collection of methods which extend the core capabilities of Ruby's
+built-in classes and modules. This collection of extension methods are unique by virtue of
+their atomicity. The methods are stored individually so that each can be required independently.
+This gives developers fine-grain control over which  extra methods to bring into his or her code.
+The collection currently contains over 400 methods spanning 28 classes and modules. It is an
+_atomic_ library in that the methods are packaged individually so that each can be _required_
+independently. This gives the programmer greater control to include only the extra methods he
+or she actually needs.
+
+Facets/MORE are a collection of classes, modules and light frameworks whcih consitutes an ever
+growing and improving source of reusable components. Some very nice additions are provided,
+from an amazing SI Units system to an elegant Annotations system. And of course there are all
+the more typical goodies like Tuple, Functor and Multiton.
 
 
 == License

data/VERSION

@@ -1 +1 @@
-1.7.38 (2006-08-31)
+1.7.46 (2006-09-08)

data/doc/CHANGELOG

@@ -1,3 +1,11 @@
+  * [deprecate] enumerable/permute.rb (replaced by permutation) and minor test fix to linkedlist.rb
+  * [added] linkedlist.rb (thanks Kirk Haines!)
+  * [added] enumerable/sum (thanks to Gavin Kistner)
+  * [added] array/each_combo and combos (Eunumerable.combinations will be deprecated eventually)
+  * [rename] changed enumerable/permute to permutation
+  * [update] annotation.rb, fixed :self key
+  * [added] pathname/op_div
+  * [deprecated] hash/each.rb
   * [removed] hash/each.rb, this variation of Hash#each is too "dangerous" in practice
   * [update] module/self/op_add.rb: fixed inclusion order
   * annotation.rb, return annotations of self when key is :self [updated]

data/lib/facet/array/combos.rb

@@ -0,0 +1 @@
+require 'facets/core/array/combos.rb'

data/lib/facet/array/each_combo.rb

@@ -0,0 +1 @@
+require 'facets/core/array/each_combo.rb'

data/lib/facet/enumerable/permutation.rb

@@ -0,0 +1 @@
+require 'facets/core/enumerable/permutation.rb'

data/lib/facet/enumerable/sum.rb

@@ -0,0 +1 @@
+require 'facets/core/enumerable/sum.rb'

data/lib/facet/linkedlist.rb

@@ -0,0 +1 @@
+require 'facets/more/linkedlist.rb'

data/lib/facet/pathname/op_div.rb

@@ -0,0 +1 @@
+require 'facets/core/pathname/op_div.rb'

data/lib/facets/core/array/combos.rb

@@ -0,0 +1,3 @@
+# stub
+require 'facets/core/array/each_combo.rb'
+

data/lib/facets/core/array/each_combo.rb

@@ -0,0 +1,48 @@
+
+class Array
+
+  # The array is expected to be and array of arrays, which
+  # iterates through combinations of each in position.
+  #
+  #   a = [ [0,1], [2,3] ]
+  #   a.each_combo { |c| p c }
+  #
+  # produces
+  #
+  #   [0, 2]
+  #   [0, 3]
+  #   [1, 2]
+  #   [1, 3]
+  #
+
+  def each_combo
+    a = collect{ |x|
+      x.respond_to?(:to_a) ? x.to_a : 0..x
+    }
+
+    if a.size == 1
+      r = a.shift
+      r.each{ |n|
+        yield n
+      }
+    else
+      r = a.shift
+      r.each{ |n|
+        a.each_combo{ |s|
+          yield [n, *s]
+        }
+      }
+    end
+  end
+
+
+  # As with each_combo but returns combos collected in an array.
+
+  def combos
+    a = []
+    each_combo{ |c| a << c }
+    a
+  end
+
+end
+

data/lib/facets/core/enumerable/{permute.rb → permutation.rb}

@@ -3,7 +3,11 @@ require 'facet/integer/factorial'
 
 module Enumerable
 
-    def permute(number)
+    # Permutation proves the possible orders of an enumerable.
+    # Each is index by a oermutation numnber. The maximum number of
+    # arrangements is the factorial of the size of the array.
+
+    def permutation(number)
         arr = to_a
         out = arr[0..0]
         nextfactor = factor = 1
@@ -18,6 +22,9 @@ module Enumerable
         }
         out
     end
+    alias :permute :permutation
+
+    #
 
     def permutation_number(original_array=self.to_a.sort)
         arr = to_a

data/lib/facets/core/enumerable/self/combinations.rb

@@ -2,7 +2,9 @@
 module Enumerable
 
   # Produces an array of arrays of all possible combinations
-  # of the given arrays in the position given. (Explain me better?)
+  # of the given arrays in the positions given. (Imagine
+  # it like a slot machine dial. This gives evey combination
+  # that could come up.)
   #
   #   a = %w|a b|
   #   b = %w|a x|
@@ -42,12 +44,19 @@ end
 
   class TCEnumerable < Test::Unit::TestCase
 
-    def test_combinations
+    def test_01
       a = [1,2]
       b = [3,4]
-      r = Enumerable.combinations(a,b)
-      assert_equal( [[1,3],[1,4],[2,3],[2,4]], r )
+      z = Enumerable.combinations(a,b)
+      r = [[1,3],[1,4],[2,3],[2,4]]
+      assert_equal( r, z )
+    end
 
+    def test_02
+      a = %w|a b|
+      b = %w|a x|
+      c = %w|x y|
+      z = Enumerable.combinations(a, b, c)
       r = [ ["a", "a", "x"],
             ["a", "a", "y"],
             ["a", "x", "x"],
@@ -56,10 +65,6 @@ end
             ["b", "a", "y"],
             ["b", "x", "x"],
             ["b", "x", "y"] ]
-      a = %w|a b|
-      b = %w|a x|
-      c = %w|x y|
-      z = Enumerable.combinations(a, b, c)
       assert_equal( r, z )
     end
 

data/lib/facets/core/enumerable/sum.rb

@@ -0,0 +1,19 @@
+#--
+# CREDIT Gavin Kistner
+#++
+
+module Enumerable
+
+  # Uses #+ to sum the enumerated elements.
+  #
+  #   [1,2,3].sum  #=> 6
+  #   [3,3,3].sum  #=> 9
+
+  def sum
+    v = 0
+    each{ |n| v+=n }
+    v
+  end
+
+end
+

data/lib/facets/core/pathname/op_div.rb

@@ -0,0 +1,4 @@
+
+class Pathname
+  alias / +
+end

data/lib/facets/more/annotation.rb

@@ -469,6 +469,15 @@ end
     end
   end
 
+  class TestAnnotation10 < Test::Unit::TestCase
+    class C
+      ann :self, :mod => 'YES'
+    end
+    def test_10_01
+      assert_equal( 'YES', C.ann.self.mod )
+    end
+  end
+
 #   class TestAnnotation10 < Test::Unit::TestCase
 #     module M
 #       ann :this, :koko => []
@@ -539,4 +548,5 @@ end
 #     end
 #   end
 
+
 =end

data/lib/facets/more/linkedlist.rb

@@ -0,0 +1,254 @@
+# = linkedlist.rb
+#
+# == Copyright (C) 2006 Kirk Haines
+#
+#   General Public License (GPL)
+#
+#   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.
+#
+# == Special Thanks
+#
+# LinkedList came from Kirk Hanes IOWA web framework.
+#
+# == Authors and Contributors
+#
+# * Kirk Haines <khaines@enigo.com>.
+#
+# == Developer Notes
+#
+# TODO Create an example of usage for docs.
+#
+
+# Author::    Jim Weirich
+# Copyright:: Copyright (c) 2006 Kirk Haines
+# License::   General Public License (GPL)
+
+require 'enumerator'
+
+# == LinkedList
+#
+# LinkedList implements a simple doubly linked list with efficient
+# hash-like element access.
+#
+# This is a simple linked list implementation with efficient random
+# access of data elements.  It was inspired by George Moscovitis'
+# LRUCache implementation found in Facets 1.7.30, but unlike the
+# linked list in that cache, this one does not require the use of a
+# mixin on any class to be stored.  The linked list provides the
+# push, pop, shift, unshift, first, last, delete and length methods
+# which work just like their namesakes in the Array class, but it
+# also supports setting and retrieving values by key, just like a
+# hash.
+
+class LinkedList
+
+        include Enumerable
+
+        # Represents a single node of the linked list.
+
+        class Node
+                attr_accessor :key, :value, :prev_node, :next_node
+
+                def initialize(key=nil,value=nil,prev_node=nil,next_node=nil)
+                        @key = key
+                        @value = value
+                        @prev_node = prev_node
+                        @next_node = next_node
+                end
+        end
+
+        def initialize
+                @head = Node.new
+                @tail = Node.new
+                @lookup = Hash.new
+                node_join(@head,@tail)
+        end
+
+        def [](v)
+                @lookup[v].value
+        end
+
+        def []=(k,v)
+                if @lookup.has_key?(k)
+                        @lookup[k].value = v
+                else
+                        n = Node.new(k,v,@head,@head.next_node)
+                        node_join(n,@head.next_node)
+                        node_join(@head,n)
+                        @lookup[k] = n
+                end
+                v
+        end
+
+        def empty?
+                @lookup.empty?
+        end
+
+        def delete(k)
+                n = @lookup.delete(k)
+                v = n ? node_purge(n) : nil
+                v
+        end
+
+        def first
+                @head.next_node.value
+        end
+
+        def last
+                @tail.prev_node.value
+        end
+
+        def shift
+                k = @head.next_node.key
+                n = @lookup.delete(k)
+                node_delete(n) if n
+        end
+
+        def unshift(v)
+                if @lookup.has_key?(v)
+                        n = @lookup[v]
+                        node_delete(n)
+                        node_join(n,@head.next_node)
+                        node_join(@head,n)
+                else
+                        n = Node.new(v,v,@head,@head.next_node)
+                        node_join(n,@head.next_node)
+                        node_join(@head,n)
+                        @lookup[v] = n
+                end
+                v
+        end
+
+        def pop
+                k = @tail.prev_node.key
+                n = @lookup.delete(k)
+                node_delete(n) if n
+        end
+
+        def push(v)
+                if @lookup.has_key?(v)
+                        n = @lookup[v]
+                        node_delete(n)
+                        node_join(@tail.prev_node,n)
+                        node_join(n,@tail)
+                else
+                        n = Node.new(v,v,@tail.prev_node,@tail)
+                        node_join(@tail.prev_node,n)
+                        node_join(n,@tail)
+                        @lookup[v] = n
+                end
+                v
+        end
+
+        def queue
+                r = []
+                n = @head
+                while (n = n.next_node) and n != @tail
+                        r << n.key
+                end
+                r
+        end
+
+        def to_a
+                r = []
+                n = @head
+                while (n = n.next_node) and n != @tail
+                        r << n.value
+                end
+                r
+        end
+
+        def length
+                @lookup.length
+        end
+
+        def each
+                n = @head
+                while (n = n.next_node) and n != @tail
+                        yield(n.key,n.value)
+                end
+        end
+
+        private
+
+        def node_delete(n)
+                node_join(n.prev_node,n.next_node)
+                v = n.value
+        end
+
+        def node_purge(n)
+                node_join(n.prev_node,n.next_node)
+                v = n.value
+                n.value = nil
+                n.key = nil
+                n.next_node = nil
+                n.prev_node = nil
+                v
+        end
+
+        def node_join(a,b)
+                a.next_node = b
+                b.prev_node = a
+        end
+
+end
+
+
+
+=begin test
+
+  require 'test/unit'
+
+  class TC_LinkedList < Test::Unit::TestCase
+
+      @cache
+
+      def test_all
+          ll = nil
+          assert_nothing_raised('Failed while creating an LinkedList object.') { ll = LinkedList.new }
+          assert_kind_of(LinkedList,ll,'Strangely, the created object does not appear to be an LinkedList.')
+
+          assert_nothing_raised('Failed while pushing a value onto the linked list.') { ll.push 'a' }
+          ll.push 'b'
+          assert_nothing_raised('Failed while assigning a key/value to the linked list.') { ll['c'] = 3 }
+          assert_equal(3,ll.first, 'First element in the linked list appears to be the wrong one.')
+          assert_equal('b',ll.last, 'Last element in the linked list appears to be the wrong one.')
+          assert_nothing_raised('Failed while unshifting a value onto the linked list.') { ll.unshift 'd' }
+          assert_equal('d',ll.first, 'The prior unshift apparently failed.')
+          assert_equal('a',ll['a'], 'Accessing an element by key failed.')
+          assert_equal(4,ll.length, 'The length of the linked list appears to be incorrect.')
+          d = nil
+          assert_nothing_raised('Failed while deleting an element from the middle of the list.') { d = ll.delete('a') }
+          assert_equal('a',d, 'The prior delete returned the wrong value for the deleted object.')
+          assert_equal(3,ll.length, 'The length of the linked list appears to be incorrect following the prior deletion.')
+          assert_nothing_raised('Failed while popping an element from the end of the list.') { d = ll.pop }
+          assert_equal('b',d, 'The prior pop returned the wrong value.')
+          assert_equal(2,ll.length, 'The length of the linked list appears to be incorrect following the prior pop.')
+          assert_equal(['d','c'],ll.queue, 'The queue of keys for the list is incorrect.')
+          assert_equal(['d',3],ll.to_a, 'Converting the list to an array (of values) seems to have failed.')
+          expected = [['c',3],['d','d']]
+          ll.each do |k,v|
+              e = expected.pop
+              assert_equal(e,[k,v], 'While iterates over the list via each(), the value from this iteration is not what was expected.')
+          end
+      end
+  end
+
+=end