carats 0.3.0

data/lib/carat/heap.rb

@@ -0,0 +1,193 @@
+=begin rdoc
+
+= Heap
+ 
+A Simple Heap structure and Sort
+
+== Extending Heap
+
+To extend the heap, implement a cmp(i,j) method which compares array
+elements i and j and returns true iff i is larger than j, where larger or
+is the required heap sorting. See Heap::Min and Heap::Max for examples.
+
+== Note
+
+The +parent+,+left+ and +right+ methods do not check the supplied parameter,
+but their result is _only_ valid if the supplied with an integer >=0 
+for +left+ and +right+ and >0 for +parent+.
+
+== Reference
+
+  <quote>
+  Cormen1990: Chapter 7 (Heapsort) of 'An introduction to algorithms', by
+  Cormen, T.H; Leiserson, C.E.; Rivest, R.L; MIT Press, Cambridge, 1990
+  ISBN 0-262-53091-0
+  </quote>
+
+== Author 
+
+* Renald Buter (buter at cwts nl)
+
+== Thanks
+
+Special thanks to Nenad Ocelic for many suggestions.
+
+== Legal
+
+Copyright (c) 2002,2004 Renald Buter (Ruby Version)
+[See Cormen1990 for original]
+
+Ruby License...
+  
+== History
+
+ $Id: heap.rb,v 1.0 2004/11/30 transami Exp $
+
+=end
+
+class Heap
+
+  class EmptyHeapException < Exception; end
+
+  # We are an abstract class
+  private_class_method :new
+  def self.inherited(sub) sub.class_eval("public_class_method :new") end
+
+  # Keeps an heap sorted with the largest element on top
+  class Max < Heap
+
+    def initialize(array=[]) super(array) end
+
+    def cmp(a,b) a > b end
+
+  end
+
+  # Keeps an heap sorted with the smallest element on top
+  class Min < Heap
+
+    def initialize(array=[]) super(array) end
+
+    def cmp(a,b) a < b end
+
+  end
+
+  # Initialise the heap. If supplied an array, build the heap with the values
+  # of the array. The array can be unsorted. Note: this method can only be
+  # called by superclasses
+  def initialize(array)
+    @array, @heap_size = array, array.length
+    (@heap_size/2 - 1).downto(0) { |i| heapify(i) }
+  end
+
+  # Get the heap size
+  def size
+    @heap_size
+  end
+
+  # Pretty print
+  def to_s
+    "<#{self.class}: size=#@heap_size, top=#{self.top}>"
+  end
+
+  # Heap-sort a clone of the internal array. This will not touch the
+  # internal array. Returns the array sorted *reversely* on the heap
+  # condition!
+  def sort
+    old_ary = @array.dup
+    old_heap = @heap_size
+    new_ary = sort_internal
+    @array = old_ary
+    @heap_size = old_heap
+    new_ary
+  end
+
+  # Heap-sort the internal array. This reduces heap size to 1, since
+  # sorting the internal array destroys the heap property. Use this only if
+  # the heap is not used after this call and you want save speed and
+  # memory; otherwise use Heap#sort. See +Heap#sort+.
+  def sort_internal
+    (@array.length-1).downto(1) do |i|
+      swap(0,i)
+      @heap_size -= 1
+      heapify(0)
+    end
+    @array
+  end
+
+  # Get the first (maximum) element on the heap
+  def top
+    raise EmptyHeapException if @heap_size < 1
+    @array[0]
+  end
+
+  # Extract the first element from the heap. Will raise EmptyHeapException
+  # if there are no (more) elements on the heap.
+  def pop
+    raise EmptyHeapException if @heap_size < 1
+    @heap_size -= 1
+    top, @array[0] = @array[0], @array[@heap_size]
+    heapify(0)
+    top
+  end
+
+  # Push an element on the heap.
+  def push(elm)
+    i = @heap_size
+    @heap_size += 1
+    while i > 0 and cmp(elm, @array[(j = parent(i))])
+      @array[i] = @array[(i = j)]
+    end
+    @array[i] = elm
+  end
+
+  # Push a list of  elements on the heap.
+  def push_all(elms)
+    elms.each {|e| push(e)}
+  end
+
+protected
+
+  # Compare elements at the supplied indices
+  def cmp_idx(i,j) 
+    cmp(@array[i], @array[j]) 
+  end
+
+  # Get the parent of the node i > 0.
+  def parent(i)
+    (i-1) >> 1 # (i-1)/2, only valid iff i > 0 !!
+  end
+
+  # Get the node left of node i >= 0
+  def left(i)
+    (i<<1) + 1 # 2i+1
+  end
+
+  # Get the node right of node i >= 0
+  def right(i)
+    (i<<1) + 2 # 2i+2
+  end
+
+  # Keeps an heap sorted with the smallest (largest) element on top
+  def heapify(i)
+    l = left i
+    top = if l < @heap_size && cmp_idx(l,i) then l else i end
+    r = right i
+    top = if r < @heap_size && cmp_idx(r,top) then r else top end
+    if top != i
+      swap(i, top)
+      heapify(top)
+    end
+  end
+
+  # Get the size of the internal array. This may be different from the heap
+  # size, e.g. after +sort+ has been called.
+  def internal_size
+    @array.size
+  end
+
+  # Swap elements in the array
+  def swap(i,j)
+    @array[i], @array[j] = @array[j], @array[i]
+  end
+
+end

data/lib/carat/html-helpers.rb

@@ -0,0 +1,82 @@
+# $Id: html.rb 2004/11/01 09:19:23 transami Exp $
+
+=begin rdoc
+
+= HTML
+ 
+Helper methods for creating HTML/XHTML documents.
+
+== Synopsis
+
+  require 'trix/xhtml'
+  
+  # [ to do ]
+  
+== Authors
+ 
+* T. Onoma
+ 
+=end
+
+require 'cgi'  # Until it has its own good escape/unescape method
+
+
+module HTML
+
+  def self.CGI_include!
+    require 'cgi'
+    CGI.class_eval { include XHTML }
+  end
+
+  def self.FCGI_include!
+    require 'fcgi'
+    FCGI.class_eval { include XHTML }
+  end
+  
+  ################
+  module_functions
+  ################
+  
+  # Create an hidden input field through which an object can can be marshalled.
+  # This makes it very easy to pass from data betwenn requests.
+  def marshal_to_html(name, iobj)
+    data = CGI.escape(Marshal.dump(iobj))
+    return %Q{<input type="hidden" name="__#{name}__" value="#{data}"/>\n}
+  end
+
+  # Create an hidden input field throught which an object can can be marshalled.
+  # This makes it very easy to pass from data betwenn requests.
+  def marshal_from_html(name)
+    return Marshal.load(CGI.unescape(self["__#{name}__"][0])) if self.params.has_key?("__#{name}__")
+  end 
+
+  # Are these good enough to replace CGI.escape?
+  
+  # Return an html "safe" version of the string,
+  # where every &, < and > are replaced with appropriate entities.
+  def esc(str)
+    str.gsub(/&/,'&amp;').gsub(/</,'&lt;').gsub(/>/,'&gt;')
+  end
+
+  # Calls #esc, and then further replaces carriage returns and quote characters with entities.
+  def escformat(str)
+    xmlsafe(str).gsub(/[\r\n]+/,'&#13;&#10;').gsub(%r|"|,'&quot;').gsub(%r|'|,'&#39;')
+  end
+
+  # Renders an object with annotations: http://tinyurl.com/6xjnj
+  # Creates a table rendering +o+'s attributes.
+  def render_object(o, collection, edit)
+    r = "<table>\n"
+    o.instance_variables.each do |attr_name| 
+    attr_value = o.instance_variable_get(attr_name)
+    attr_anns = o.class.send(attr_name[1..-1])
+      r << "  <tr>\n"
+      r << "    <td>" << attr_anns[:description] << "</td>\n"
+      r << "    <td>" << text_or_input(edit, :name => "#{collection}[#{o.class.name}][#{attr_name}]", :value => attr_value) << "</td>\n"
+      r << "  </tr>\n"
+    end
+    r << "</table>"
+    r
+  end
+
+end

data/lib/carat/infinity.rb

@@ -0,0 +1,61 @@
+=begin rdoc
+
+= Infinity
+
+A full featured Infinity class, supporting aleph levels and signed 
+direction. Inifinty is a multiton based on the aleph and direction 
+values. The conastant INFINITY is provided as the common case with 
+aleph=0 and direction=+1 (positive).
+
+= Author(s)
+
+* Thomas Sawyer
+
+=end
+
+
+require 'carat/multiton'
+
+
+class Infinity < Numeric
+  include Multiton
+
+  def self.[](a)
+    self.new(a)
+  end
+  
+  attr_reader :aleph, :direction
+    
+  def initialize(aleph=0, direction=1)
+    @aleph = aleph
+    @direction = direction
+  end
+  
+  def -@
+    self.class.instance(@aleph, @direction * -1)
+  end
+  
+  def to_f
+    (1.0/0) * @direction
+  end
+  
+  def times
+    loop do
+      yield
+    end
+  end
+
+  def <=>(x)
+    return (x.kind_of?(Infinity) ? (@aleph <=> x.aleph) : @direction)
+  end
+  
+  def to_s
+    %Q{#{ '-' if @direction == -1 }Infinity[#{@aleph}]}
+  end
+  
+end
+
+# constant (for aleph=0)
+INFINITY = Infinity.instance
+
+

data/lib/carat/init.rb

@@ -0,0 +1,33 @@
+
+=begin rdoc
+
+= Init
+
+Allows you to use #init inplace of #initialize. It does this by
+aliasing initialize to init when it is defined.
+
+== Synopsis
+
+  require 'carat/init'
+  
+  class T
+    def init
+      puts "Here"
+    end
+  end
+  
+  t = T.new   #=> "Here"
+
+== Author(s)
+
+* Thaoms Sawyer
+
+=end
+
+class Class
+  def method_added( meth )
+    if meth == :init
+      self.class_eval { alias initialize init }
+    end
+  end
+end

data/lib/carat/interval.rb

@@ -0,0 +1,248 @@
+=begin rdoc
+
+= Interval
+
+While Ruby support the Range class out of the box, is does not quite 
+fullfil the role od a real Interval class. For instance, it does
+not support excluding the front sentinel. This is because Range
+also tries to do triple duty as a simple Sequence and as a simple Tuple-Pair,
+thus limiting its potential as an Interval. The Interval class remedies
+the situation by commiting to interval behavior, and then extends the class'
+capabilites beyond that of the standard Range in ways that naturally
+fall out of that.
+
+Range depends on two methods: #succ and #<=>. If numeric
+ranges were the only concern, those could just as well be #+ and #<=>,
+but esoteric forms make that unfeasible --the obvious example being a String
+range. But a proper Interval class requires mathematical continuation,
+thus the Interval depends on #+ and #<=>, as well as #- as the inverse of #+.
+
+== Synopsis
+
+  require 'carat/facet'
+
+  i = Interval.new(1,5)
+  i.to_a       #=> [1,2,3,4,5]
+
+  i = Interval[0,5]
+  i.to_a(2)    #=> [0,2,4]
+
+  i = Interval[1,5]
+  i.to_a(-1)   #=> [5,4,3,2,1]
+
+  i = Interval[1,3]
+  i.to_a(1,2)  #=> [1.0,1.5,2.0,2.5,3.0]
+
+== Author(s)
+
+* Thomas Sawyer
+
+== Legal
+
+Ruby License
+Copyright (c)2005 Thomas Sawyer
+
+=end
+
+require 'carat/multiton'
+require 'carat/enumerable-args'
+#require 'carat/infinity'
+
+class Interval
+  include Multiton::New
+  include EnumerableWithArgs
+
+  def self.[]( *args )
+    self.new( *args )
+  end
+   
+  def initialize(first, last, exclude_first=false, exclude_last=false )
+    raise ArgumentError, "bad value for interval" if first.class != last.class
+    @first = first
+    @last = last
+    @exclude_first = exclude_first
+    @exclude_last = exclude_last
+    @direction = (@last <=> @first)
+  end
+    
+  # Returns a two element array of first and last sentinels.
+  #   
+  #  (0..10).sentinels   #=> [0,10]
+  #
+  def sentinels
+    return [@first, @last]
+  end
+  
+  # Returns the first or last sentinal of the interval.
+  def first ; @first ; end
+  def last ; @last ; end
+  
+  #   
+  def exclude_first? ; @exclude_first ; end
+  def exclude_last? ; @exclude_last ; end
+  
+  # (IMHO) these should be deprectated
+  alias_method( :begin, :first )
+  alias_method( :end, :last )
+  alias_method( :exclude_begin?, :exclude_first? )
+  alias_method( :exclude_end?, :exclude_last? )
+
+  # Returns +true+ if the start and end sentinels are equal and the interval is closed; otherwise +false+.
+  def degenerate? ; @direction == 0 and ! (@exclusive_first or @exclusive_last) ;  end
+  
+  # Returns +true+ if the start and end sentinels are equal and the interval is open; otherwise +false+.
+  def null? ; @direction == 0 and @exclusive_first and @exclusive_last ; end
+  
+  # Returns the direction of the interval indicated by +1, 0 or -1.
+  #
+  #   (1..5).direction  #=> 1
+  #   (5..1).direction  #=> -1
+  #   (1..1).direction  #=> 0
+  #
+  def direction ; @direction ; end
+  
+  # Returns a new interval inclusive of of both sentinels.
+  def closed; Interval.new(@first, @last, true, true) ; end
+  
+  # Returns a new interval exclusive of both sentinels.
+  def opened; Interval.new(@first, @last, true, true) ; end
+  
+  # Returns a new interval with either the first or the last sentinel exclusive.
+  # If the parameter is false, the deafult, then the first sentinel is excluded;
+  # if the parameter is true, the last sentinel is excluded.
+  def half_closed(e=false)
+    e ? Interval.new(@first, @last, true, false) : Interval.new(@first, @last, false, true)
+  end
+  
+  # Returns a new interval with one of the two sentinels opened or closed
+  def first_closed ; Interval.new(@first, @last, false, true) ; end
+  def last_closed ; Interval.new(@first, @last, true, false) ; end
+  def first_opened ; Interval.new(@first, @last, true, false) ; end
+  def last_opened ; Interval.new(@first, @last, false, true) ; end
+  
+  # Unary shorthands. These return a new interval exclusive of first,
+  # last or both sentinels, repectively.
+  def +@ ; Interval.new(first, last, true, false) ; end
+  def -@ ; Interval.new(first, last, false, true) ; end
+  def ~@ ; Interval.new(first, last, true, true) ; end
+
+  # Returns a new interval with the sentinels reversed.
+  #
+  #   (0..10).reversed  #=> 10..0
+  #
+  def reversed
+    Interval.new(@last, @first, true, true)
+  end
+  
+  # Returns the length of the interval as the difference between
+  # the first and last elements. Returns +nil+ if the sentinal objects
+  # do not support distance comparison (#distance).
+  # TODO: Add +n+ parameter to count segmentations like those produced by #each.
+  def distance
+    @last - @first
+    #if @last.respond_to?( :distance )
+    #  @last.distance( @first )
+    #else
+    #  #self.to_a.length
+    #end
+  end
+  alias_method( :length, :distance )
+  alias_method( :size, :distance )
+    
+  # Returns the lesser of the first and last sentinals.
+  def min
+    ((@first <=> @last) == -1) ? @first : @last
+  end
+
+  # Returns the greater of the first and last sentinals.
+  def max
+    ((@first <=> @last) == 1) ? @first : @last
+  end
+
+  # Returns true or false if the element is part of the interval.
+  def include?(x)
+    # todo: infinity?   
+    tf = exclude_first? ? 1 : 0
+    tl = exclude_last? ? -1 : 0
+    (x <=> first) >= tf and (x <=> last) <= tl
+  end
+  alias_method( :===, :include? )
+  alias_method( :member?, :include? )
+
+=begin
+#     def include?(x)
+#       tf = exclude_first? ? 1 : 0
+#       tl = exclude_last? ? -1 : 0
+#       # if other classes handled Infinity in their <=> method
+#       # (which probably they should) this clause would not be required
+#       if first.kind_of?(InfinityClass)
+#         ft = ((first <=> x) <= tf)
+#       else
+#         ft = (x <=> first) >= tf
+#       end
+#       if last.kind_of?(InfinityClass)
+#         fl = ((last <=> x) >= tl)
+#       else
+#         fl = (x <=> last) <= tl
+#       end
+#       ft && fl
+#     end
+=end
+
+  # Iterates over the interval, passing each _n_th element to the block. 
+  # If n is not given then n defaults to 1. Each _n_th step is determined
+  # by invoking +\++ or +\-+ n, depending on the direction of the interval.
+  # If n is negative the iteration is preformed in reverse form end sentinal
+  # to front sentinal. A second parameter, d, can be given in which case
+  # the applied step is calculated as a fraction of the interval's length
+  # times n / d. This allows iteration over the whole interval in equal sized
+  # segments.
+  #
+  #   1..5.each { |e| ... }        #=> 1 2 3 4 5
+  #   1..5.each(2) { |e| ... }     #=> 1 3 5
+  #   1..5.each(1,2) { |e| ... }   #=> 1.0 1.5 2.0 2.5 3.0 3.5 4.0 4.5 5.0
+  #
+  def each(n=1, d=nil)  # :yield:   
+    return (n < 0 ? @last : @first) if degenerate?  # is this right for all values of n ?
+    s = d ? self.length.to_f * (n.to_f / d.to_f) : n.abs
+    raise "Cannot iterate over zero length steps." if s == 0
+    s = s * @direction
+    if n < 0
+      e = @exclude_last ? @last - s : @last
+      #e = @exclude_last ? @last.pred(s) : @last
+      t = @exlude_last ? 1 : 0
+      #while e.cmp(@first) >= t
+      while (e <=> @first) >= t
+        yield(e)
+        e -= s
+        #e = e.pred(s)
+      end
+    else
+      e = @exclude_first ? @first + s : @first
+      #e = @exclude_first ? @first.succ(s) : @first
+      t = @exlude_last ? -1 : 0
+      #while e.cmp(@last) <= t
+      while (e <=> @last) <= t
+        yield(e)
+        e += s
+        #e = e.succ(s)
+      end
+    end
+  end
+  alias_method( :step, :each )
+
+  # Should there be a #reverse_each ?
+  # Since #each can now take a negative argument, this isn't really needed.
+  # Should it exist anyway and routed to #each?
+  # Also, alias_method( :reverse_step, :reverse_each )
+
+  # Compares two intervals to see if they are equal
+  def eql?(other)
+    return false unless @first == other.first
+    return false unless @last == other.last
+    return false unless @exclude_first == other.exclude_first?
+    return false unless @exclude_last == other.exclude_last?
+    true
+  end
+  
+end