facets-glimmer 3.2.0

data/demo/standard/memoizable.rdoc

@@ -0,0 +1,134 @@
+= Memoizable
+
+Memoizable allows
+
+  require 'facets/memoizable'
+
+The classic example is calculating the Fibonacci sequence.
+
+  class Fibonacci
+    include Memoizable
+
+    def fib( num )
+      return num if num < 2
+      fib(num - 1) + fib(num - 2)
+    end
+
+    memoize :fib
+  end
+
+The first time will take a moment to calculate.
+
+  f = Fibonacci.new
+  f.fib(100)
+
+The second time will be returned almost instantly.
+
+  f = Fibonacci.new
+  f.fib(100)
+
+The following example makes if very clear what memoize is doing.
+
+  class MemoExample
+    include Memoizable
+    attr_accessor :a
+    memoize :a
+  end
+
+  m = MemoExample.new
+  m.a = 10
+  m.a         #=> 10
+  m.a = 20
+  m.a         #=> 10
+
+Even though @a is assigned to 20, the method #a continues to return 10.
+
+Memoizable is designed to handle a number of typically problematic aspects
+of memoization implementations. First a memoizable object can be frozen.
+
+  f = Fibonacci.new
+  f.freeze
+  f.fib(100)
+
+Memoizable objects are freezable because it does not use an instance variable
+to store the memoized return values. Instead it uses a global class instance
+variable in +Memoizable.cache+.
+
+However, this also means the memoization cache is not preserved when an object
+is duplicated. If this behavior is desired an aditional module is provided
+called `Memoizable::Copy`. When the `Memoiazble::Copy` module is included into
+a class it not only adds the #memoize class methods but also includes
+an #initialize_copy method, which copies the appropriate cache entries when
+#dup or #clone is used. Keep this in mind. It is important to call #super if you
+override the #initialize_copy method in a class that uses `Memoizable::Copy`.
+
+  class MemoExample2
+    include Memoizable::Copy
+    attr_accessor :a
+    memoize :a
+  end
+
+  m = MemoExample2.new
+  m.a = 10
+  m.a         #=> 10
+
+  n = m.dup
+  n.a = 20
+  n.a         #=> 10
+
+The `#memoize` method also accepts a few options that can be used to modify
+the behvior of the memoizaiton. To memoize a method across all objects
+of the same class and not just per-object, set the `:class` option to true.
+
+  class MemoExample3
+    include Memoizable
+    attr_accessor :a
+    memoize :a, :class=>true
+  end
+
+  m = MemoExample3.new
+  m.a = 10
+  m.a         #=> 10
+
+  n = MemoExample3.new
+  n.a         #=> 10
+
+Memoization is indexed based on arguments passed to the method, as can be seen 
+in the Fibonacci example. Methods can also be memoized by name only, forgoing
+any indexing based on arguments passed. To do this, set the `:arguments`
+option to +false+.
+
+  class MemoExample4
+    include Memoizable
+    def f(n)
+      n + n
+    end
+    memoize :f, :arguments=>false
+  end
+
+  m = MemoExample4.new
+  m.f(1)
+  m.f(2)      #=> 2
+  m.f(3)      #=> 2
+
+Blocks passed to a method normally have only a present vs. non-present effect
+on the memoization index. In other words the return value of a method will be
+cached under one key if a block is passed to it and under a different index
+if not. It doesn't matter if blocks passed in actually differ, since
+the only way to compare blocks is by their +object_id+ and it is very rare
+for the exact same block object to be reused.
+
+Finally, the `:freeze` option can be used to freeze the memoized results.
+
+  class MemoExample5
+    include Memoizable
+    def f(n)
+      (n + n).to_s
+    end
+    memoize :f, :freeze=>true
+  end
+
+  m = MemoExample5.new
+  m.f(1).frozen?      #=> true
+  m.f(2).frozen?      #=> true
+

data/demo/standard/mulititon.rdoc

@@ -0,0 +1,156 @@
+= Multiton
+
+The Multion pattern is essentially the same as the Singleton pattern, but
+unlike it's fully unique brethren Multiton's are identical if their
+initialization parameters are identical.
+
+To demontrate we first need to load the Facets multiton.rb script.
+
+  require 'facets/multiton'
+
+Now for the various exmples.
+
+
+== EXAMPLE A - STANDARD USAGE
+
+    class SomeMultitonClass
+      include Multiton
+
+      attr :arg
+      def initialize(arg)
+        @arg = arg
+      end
+    end
+
+    a = SomeMultitonClass.instance(4)
+    b = SomeMultitonClass.instance(4)     # a and b are same object
+    c = SomeMultitonClass.instance(2)     # c is a different object
+
+    a.assert == b 
+
+    x = [a.arg, b.arg].max * 10 + c.arg
+    x.assert == 42
+
+
+== EXAMPLE B - MODIFY AN EXISTING CLASS
+
+We can modify an existing class (if we are so bold), for example we can
+add shared filehandles to the File class.
+
+    class ::File
+      include Multiton
+    end
+
+    lineno = __LINE__
+    # HERE1
+    # HERE2
+
+    a = File.instance(__FILE__)
+    b = File.instance(__FILE__)
+
+    b.assert == a
+
+    lineno.times{ a.gets }
+
+    a.gets.strip.assert == "# HERE1"
+    b.gets.strip.assert == "# HERE2"
+
+
+== EXAMPLE C - INHERITENCE
+
+  class A < String
+    include Multiton
+  end
+
+  # B is also a multiton - with it's OWN object cache
+  class B < A; end
+
+  # w is the same object as x, y is the same object as z
+  w,x,y,z = A.instance('A'), A.instance('A'), B.instance('B'), B.instance('B')
+
+  x.object_id.assert == w.object_id
+  z.object_id.assert == y.object_id
+
+  a = B.instance('A')
+  b = B.instance('A')
+
+  w.object_id.refute == a.object_id   # (each class has it's own pool)
+  b.object_id.assert == a.object_id
+
+
+== EXAMPLE D - MULTIPLE MODULE INCLUSION (does nothing)
+
+  class A < String
+    include Multiton
+  end
+
+  # B is also a multiton - with it's OWN object cache
+  class B < A; end
+
+
+  # w is the same object as x, y is the same object as z
+  w,x,y,z = A.instance('A'), A.instance('A'), B.instance('B'), B.instance('B')
+
+  yz_id = y.object_id || z.object_id
+
+If we include Multiton again, it will have to effect.
+
+  B.class_eval {
+    include Multiton
+  }
+
+  # y is not only the same object as z, but they are both the same object(s)
+  # as from EXAMPLE C
+
+  y,z = B.instance('B'), B.instance('B')
+
+  yz_id.assert == y.object_id
+  yz_id.assert == z.object_id
+
+
+== EXAMPLE E - SO YOU WANNA USE NEW INSTEAD OF INSTANCE
+
+  module K
+    # use an inner class which is itself a multiton
+    class K < String; include Multiton; end
+
+    # define a new which returns a mutltion using #instance...
+    class << self
+      def new(*args, &block)
+        K.instance(*args, &block)
+      end
+    end
+  end
+
+  the = K.new '4'
+  answer = K.new '2'
+
+  x = sprintf( "%s%s", the, answer )
+  x.assert == "42"
+  the.class.assert == K::K
+
+
+== EXAMPLE F - using Klass.multiton_id
+
+  class Klass
+    include Multiton
+
+    def initialize( important, not_important )
+      @important, @not_important = important, not_important
+    end
+
+    def Klass.multiton_id(*args, &block)
+      # we consider only the first arg
+      important, not_important = *args
+      important
+    end
+  end
+
+  a = Klass.instance( :a, :b )
+  b = Klass.instance( :a, :c )
+  c = Klass.instance( :b, :b )
+
+  a.assert == b
+  c.refute == a
+  c.refute == b
+

data/lib/core/facets/applique/file_helpers.rb

@@ -0,0 +1,33 @@
+#
+def temporary_directory
+  @temporary_directory ||= 'tmp'
+end
+
+When /Given a directory '(.*?)' containing/ do |dir, text|
+  @temporary_directory = File.join(@temporary_directory, dir)
+  text.lines.each do |file|
+    next if file =~ /^\s*$/
+    file = File.join(@temporary_directory, file.strip)
+    dir  = File.dirname(file)
+    FileUtils.mkdir_p(dir)
+    File.open(file, 'w'){ |f| f << "SPINICH" }
+  end
+end
+
+Before :all do
+  if File.exist?(temporary_directory)
+    FileUtils.rm_r(temporary_directory)
+  end
+  FileUtils.mkdir_p(temporary_directory)
+end
+
+# Used for File extensions
+When "had a file '(((.*?)))'" do |name|
+  name = name.sub(/^tmp\//, '')  # b/c QED now runs from tmp/qed
+  File.open(name, 'w'){|f| f << "Hello World"}
+end
+
+When "had a binary file '(((.*?)))'" do |name|
+  name = name.sub(/^tmp\//, '')  # b/c QED now runs from tmp/qed
+  File.open(name, 'wb'){|f| f << "Hello\nWorld\n"}
+end

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

@@ -0,0 +1 @@
+require 'facets/array/before'

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

@@ -0,0 +1,42 @@
+class Array
+
+  # The `arrange` method produces appropriate ranges from the objects in the array.
+  #
+  # Examples
+  #
+  #     [1,2,3,6,7,8].arrange  #=> [1..3, 6..8]
+  #
+  #     [10..15, 16..20, 21, 22].arrange  #=> [10..22]
+  #
+  # Assumes inclusive ranges (ie. 1..4) and range.first <= range.last.
+  #
+  # Works with integers, dates and strings. However, all the objects in the array must
+  # be of the same class.
+  #
+  # CREDIT: monocle
+
+  def arrange
+		array = uniq.sort_by { |e| Range === e ? e.first : e }
+		array.inject([]) do |c, value|
+			unless c.empty?
+				last = c.last
+				last_value    = (Range === last  ? last.last   : last)
+				current_value = (Range === value ? value.first : value)
+				if (last_value.succ <=> current_value) == -1
+					c << value
+				else
+					first  = (Range === last ? last.first : last)
+					second = [Range === last ? last.last : last, Range === value ? value.last : value].max
+					c[-1] = [first..second]
+					c.flatten!
+				end
+			else
+				c << value
+			end
+		end
+	end
+
+  alias rangify arrange
+
+end
+

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

@@ -0,0 +1,15 @@
+class Array
+
+  # Calculate the average of an array of numbers
+  #
+  # Examples
+  #
+  #   [].average #=> nil
+  #   [1, 2, 3].average #=> 2
+  #   [3, 12, 57, 85, 15, 89, 33, 7, 22, 54].average #=> 37.7
+  #
+  def average
+    return nil if empty?
+    self.reduce(:+)/length.to_f
+  end
+end

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

@@ -0,0 +1,41 @@
+class Array
+
+  # Returns the value previous to the given value. The value previous
+  # to the first is the last. Returns nil if the given value is not
+  # in the array.
+  #
+  # Examples
+  #
+  #   sequence = ['a', 'b', 'c']
+  #   sequence.before('a')           #=> 'c'
+  #   sequence.before('b')           #=> 'a'
+  #   sequence.before('c')           #=> 'b'
+  #   sequence.before('d')           #=> nil
+  #
+  # CREDIT: Tyler Rick
+
+  def before(value)
+    return nil unless include? value
+    self[(index(value).to_i - 1) % length]
+  end
+
+  # Returns the value after the given value. The value before the last
+  # is the first. Returns nil if the given value is not in the array.
+  #
+  # Examples
+  #
+  #   sequence = ['a', 'b', 'c']
+  #   sequence.after('a')           #=> 'b'
+  #   sequence.after('b')           #=> 'c'
+  #   sequence.after('c')           #=> 'a'
+  #   sequence.after('d')           #=> nil
+  #
+  # CREDIT: Tyler Rick
+
+  def after(value)
+    return nil unless include? value
+    self[(index(value).to_i + 1) % length]
+  end
+
+end
+

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

@@ -0,0 +1,18 @@
+class Array
+
+  # Simplify an array by flattening it then compacting it.
+  #
+  # Examples
+  #
+  #   [1,[2,nil,[3]],nil,4].collapse  #=> [1,2,3,4]
+  #
+  def collapse
+    flatten.compact
+  end
+
+  def collapse!
+    flatten!.compact!
+  end
+
+end
+

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

@@ -0,0 +1 @@
+require 'facets/array/commonality'

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

@@ -0,0 +1,49 @@
+class Array
+
+  # Get a list of all items that have something in common in terms of the
+  # supplied block. If no block is given objects are considered to be in 
+  # common if they return the same value for Object#hash and if obj1 == obj2.
+  #
+  # This can be useful, for instance, in determining all persons that share
+  # their last name with another person.
+  #
+  #     persons.commonality { |person| person.last_name }
+  #
+  # The method is similar to #group_by which is a standard Ruby method as of 1.9.
+  # To get effectively the same results with #group_by use `select{ |k,v| v.size > 1 }`.
+  #
+  #     [1, 2, 2, 3, 4, 4].group_by{ |e| e }.select{ |k,v| v.size > 1 }
+  #     #=> { 2 => [2, 2], 4 => [4, 4] }
+  #
+  # Examples
+  #
+  #   [1, 2, 2, 3, 4, 4].commonality  #=> { 2 => [2, 2], 4 => [4, 4] }
+  #
+  #   ["foo", "bar", "baz"].commonality { |str| str[0] }
+  #   #=> { 'b' => ["bar", "baz"] }
+  #
+  # Returns [Hash] mapping common attribute to those elements. 
+  #
+  # CREDIT: Florian Gross
+
+  def commonality(&block)
+    block ||= lambda { |item| item }
+
+    result = Hash.new { |hash, key| hash[key] = Array.new }
+    each do |item|
+      key = block.call(item)
+      result[key] << item
+    end
+
+    result.reject! do |key, values|
+      values.size <= 1
+    end
+
+    return result
+  end
+
+  # Deprecated: Alias for #commonality.
+  alias collisions commonality
+
+end
+

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

@@ -0,0 +1,89 @@
+class Array
+
+  # This is more advanced form of #join. It allows for fine control
+  # of separators.
+  #
+  # NOTE: The old version used to default its separator to ", " and
+  # default the terminating separator to " and ". This is no longer
+  # the case. You must specifically provide these parameters.
+  #
+  # If no paramters are given, it acts like #join but will a space
+  # separator.
+  #
+  #   [1,2,3].conjoin
+  #   #=> "1 2 3"
+  #
+  # Use comma+space and 'and' on tail.
+  #
+  #   [1,2,3].conjoin(', ', ' and ')
+  #   #=> "1, 2 and 3"
+  #
+  # Use comma+space and 'or' on tail using :last option.
+  #
+  #   [1,2,3].conjoin(', ', :last => ' or ')
+  #   #=> "1, 2 or 3"
+  #
+  # Use semicolon+space and ampersand on tail using index.
+  #
+  #   [1,2,3].conjoin('; ', -1 => ' & ')
+  #   #=> "1; 2 & 3"
+  #
+  # Can take a block to determine separator.
+  #
+  #   [1,2,3,4].conjoin{ |i, a, b| i % 2 == 0 ? '.' : '-' }
+  #   #=> "1.2-3.4"
+  #
+  # This makes very esoteric transformation possible.
+  #
+  #   [1,1,2,2].conjoin{ |i, a, b| a == b ? '=' : ' != ' }
+  #   #=> "1=1 != 2=2"
+  #
+  #   [1,2,3,4].conjoin{ |i, x, y| "<#{i} #{x} #{y}>" }
+  #   #=> "1<0 1 2>2<1 2 3>3<2 3 4>4"
+  #
+  # There are also spacing options. Providing the :space option
+  # pads the separators.
+  #
+  #   [1,2,3].conjoin(',', '&', :space=>2)
+  #   #=> "1  ,  2  &  3"
+  #
+  # And the :spacer option can set an alternate spacing string.
+  #
+  #   [1,2,3].conjoin('|', '>', :space=>2, :spacer=>'-')
+  #   #=> "1--|--2-->--3"
+  #
+  # CREDIT: Trans
+
+  def conjoin(*args, &block)
+    return first.to_s if size < 2
+
+    options = (Hash===args.last) ? args.pop : {}
+
+    spacing = options.delete(:space)  || 0
+    spacer  = options.delete(:spacer) || " "
+    space   = spacer * spacing.to_i
+
+    sep = []
+
+    if block_given?
+      (size - 1).times do |i|
+        sep << space + yield(i, *slice(i,2)) + space
+      end
+    else
+      separator   = args.shift || " "
+      options[-1] = args.shift if args.first
+
+      options[0]  = options.delete(:first) if options.key?(:first)
+      options[-1] = options.delete(:last)  if options.key?(:last)
+
+      separator = space + separator + space
+
+      sep = [separator] * (size - 1)
+
+      options.each{|i, s| sep[i] = space + s + space}
+    end
+    zip(sep).join
+  end
+
+end
+

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

@@ -0,0 +1,7 @@
+class Array
+
+  # Alias for #include?.
+  alias_method :contains?, :include?
+
+end
+

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

@@ -0,0 +1,4 @@
+# Here for backward compatability. To be deprecated.
+require 'facets/array/delete_unless'
+require 'facets/array/delete_values'
+

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

@@ -0,0 +1,15 @@
+class Array
+
+  # Inverse of #delete_if.
+  #
+  #   [1,2,3].delete_unless{ |x| x < 2 }
+  #   #=> [1]
+  #
+  # CREDIT: Daniel Schierbeck
+
+  def delete_unless(&block)
+    delete_if { |element| not block.call(element) }
+  end
+
+end
+

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

@@ -0,0 +1,50 @@
+class Array
+
+  # Delete multiple values from array.
+  #
+  #   a = [1,2,3,4]
+  #   a.delete_values(1,2)   #=> [1,2]
+  #   a                      #=> [3,4]
+  #
+  # CREDIT: Trans
+
+  def delete_values(*values)
+    d = []
+    values.each{ |v| d << delete(v) }
+    d
+  end
+
+  # Delete multiple values from array given
+  # indexes or index range.
+  #
+  #   a = [1,2,3,4]
+  #   a.delete_values_at(1,2)   #=> [2,3]
+  #   a                         #=> [1,4]
+  #   a = [1,2,3,4]
+  #   a.delete_values_at(0..2)  #=> [1,2,3]
+  #   a                         #=> [4]
+  #
+  # NOTE: It would be nice to see #delete_at incorporate this
+  # funcitonaility.
+  #
+  # CREDIT: Trans
+
+  def delete_values_at(*selectors)
+    idx = []
+    selectors.each{ |i|
+      case i
+      when Range
+        idx.concat( i.to_a )
+      else
+        idx << i.to_i
+      end
+    }
+    idx.uniq!
+    dvals = values_at(*idx)
+    idx = (0...size).to_a - idx
+    self.replace( values_at(*idx) )
+    return dvals
+  end
+
+end
+

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

@@ -0,0 +1 @@
+require 'facets/array/delete_values'

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

@@ -0,0 +1,27 @@
+class Array
+
+  # Divide on matching pattern.
+  #
+  #   ['a1','b1','a2','b2'].divide(/^a/)
+  #   #=> [['a1','b1'],['a2','b2']]
+  #
+  #   ['a1','b1','a2','b2'].divide(/^b/)
+  #   #=> [['a1',['b1','a2'],[]'b2']]
+  #
+  #   ['a1','b1','a2','b2'].divide(/^c/)
+  #   #=> [['a1','b1','a2','b2']]
+  #
+  # CREDIT: Trans
+
+  def divide(pattern)
+    memo = []
+    memo.push [] unless pattern === first
+    each do |obj|
+      memo.push [] if pattern === obj
+      memo.last << obj
+    end
+    memo
+  end
+
+end
+