facets 1.3.0 → 1.3.1

data/lib/facets/more/basicobject.rb

@@ -70,6 +70,8 @@ require 'facets/core/kernel/__class__'
 
 class BasicObject
 
+  alias_method :__method__, :method
+
   #EXCLUDE = /^(__id__|__send__)$/
   EXCLUDE = /(^__|^instance_|^object_|^null$|^inspect$|^dup$|\?$)/
 

data/lib/facets/more/builderobject.rb

@@ -0,0 +1,216 @@
+#--
+# BuilderFactory
+# Copyright (c) 2006 Thomas Sawyer
+#
+# Ruby License
+#
+#++
+
+require 'rexml/document'
+
+require 'facets/core/hash/keys_to_s'
+require 'facets/core/kernel/own'
+require 'facets/more/functor' # already requires basicobject
+
+# :title: BuilderObject
+#
+# Build structures programatically with Ruby and Ruby's blocks.
+#
+# Builders can use either an implict or explicit receiver.
+# Explicit is the default. To use implicit pass the :implicit
+# option to the constructor.
+#
+# Implict building is more elegant in form, but it is not as
+# functional because it makes it more difficult to refer to
+# external references.
+#
+# BuilderObject avoides metrhod name clashes by using
+# Functor redirection. Unlike other implementations of
+# the Builder patterns which append '!' to builder methods
+# or simply use odd names to avoid clashes, BuilderObject
+# routes all builder method vis the #out method.
+#
+# NOTE The name of this method (#out) may be changed.
+
+class BuilderObject < BasicObject
+
+  # Builder mixin.
+
+  def self.builder
+    @builder ||= Module.new
+  end
+
+  def self.builder_include( *mod )
+    builder.module_eval { extend *mod }
+  end
+
+private
+
+  def builder
+    self.__class__.builder
+  end
+
+  # Prepare builder.
+
+  def initialize( *options )
+    # initialize options
+    @options = (Hash === options.last ? options.pop : {} )
+    options.each { |o| @options[o] = true }
+    # initialize stack
+    @stack = []
+    # initialize buffer
+    @target = builder.new( @options )
+  end
+
+  # Core of Builder's functionality.
+
+  def method_missing( tag, *args, &block )
+    if @current and block_given?
+      @stack << @target
+      @target = @current
+      if @options[:implicit]
+        instance_eval( &block )
+      else
+        block.call
+      end
+      @target = @stack.pop
+    end
+    @target
+  end
+
+  # Creates object via builder modules,
+  # stores as current and appends to buffer.
+
+  def +( op, *args, &blk )
+    obj = builder.send( op, *args, &blk )
+    @current = obj
+    @target << obj
+    self
+  end
+
+public
+
+  # raw insert
+
+  def <<( str )
+    r = builder.raw( str )
+    if Array === r
+      r.each { |e| @target << e }
+    else
+      @target << r
+    end
+    self
+  end
+
+  # Redirection functor.
+  #--
+  # TODO Better name?
+  #++
+
+  def out( str=nil )
+    if str
+      self << str
+    else
+      @builder_functor ||= Functor.new( &__method__(:+) )
+    end
+  end
+
+  # text output
+
+  def to_s
+    @target.to_s
+  end
+
+end
+
+
+# Some prebuilt mixin modules for creating builders.
+# These could also be used without builder.
+
+module BuilderObject::REXML
+
+  extend self
+
+  # Add raw XML markup
+
+  def raw( str )
+    REXML::Document.new( "<root>#{str}</root>" ).root.to_a
+  end
+
+  # New REXML document.
+
+  def document( options={} )
+    @options = options
+    doc = REXML::Document.new
+    # xml declaration
+    if options[:version]
+      doc << xml(
+        options[:version],
+        options[:encoding],
+        options[:standalone]
+      )
+    end
+    doc
+  end
+
+  # Used for initial buffer value in a builder.
+
+  alias_method :new, :document
+
+  # XML declaration
+
+  def xml( version=nil, *args )
+    REXML::XMLDecl.new( version=nil, *args )
+  end
+
+  def element( tag, *args )
+    keys = (Hash === args.last ? args.pop : {})
+    e = REXML::Element.new( tag )
+    e.add_attributes( keys.keys_to_s )
+    e.add_text(args.join(' ')) unless args.empty?
+    e
+  end
+
+  def instruct( name, *args )
+    keys = (Hash === args.last ? args.pop : {})
+    content = ( args + keys.collect{ |k,v| %{#{k}="#{v}"} } ).join(' ')
+    REXML::Instruction.new( name, content.strip )
+  end
+  alias_method :instruction, :instruct
+  alias_method :pi, :instruct
+
+  def text( str, *args )
+    REXML::Text.new( str, *args )
+  end
+
+  def comment( str, *args )
+    REXML::Comment.new( str, *args )
+  end
+
+  def cdata( str, *args )
+    REXML::CData.new( str, *args )
+  end
+
+  # DTD declarations
+
+  def doctype!( *args )
+    REXML::DocType.new( *args )
+  end
+
+  def element!( *args )
+    REXML::ElementDecl.new( *args )
+  end
+
+  def attlist!( *args )
+    REXML::AttlistDecl.new( *args )
+  end
+
+  def entity!( *args )
+    REXML::EntityDecl.new( *args )
+  end
+
+  def notation!( *args )
+    REXML::NotationDecl.new( *args )
+  end
+
+end

data/lib/facets/more/functor.rb

@@ -14,10 +14,13 @@
 # ==========================================================================
 #  Revision History
 # ==========================================================================
-#  05-09-22  trans
+#  2006-04-15
+#    Code cleanup, changed instance_objects to instance_targets.
+#
+#  2005-09-22  trans
 #    Made a subclass of BasicObject.
 #
-#  05-01-10  trans
+#  2005-01-10  trans
 #    Ported to Facets.
 # ==========================================================================
 #++
@@ -33,8 +36,6 @@ require 'facets/more/basicobject'
 #
 # == Synopsis
 #
-#   require 'mega/functor'
-#
 #   f = Functor.new { |op, x| x.send(op, x) }
 #   f + 1  #=> 2
 #   f + 2  #=> 4
@@ -50,22 +51,22 @@ require 'facets/more/basicobject'
 
 class Functor < BasicObject
 
-  def initialize(*obj, &func)
-    @obj = obj
-    @func = func
+  def initialize(*targets, &function)
+    @targets = targets
+    @function = function
   end
 
   def method_missing(op, *args, &blk)
     if block_given?
-      @func.call(op, *(@obj + args + [blk]))
+      @function.call(op, *(@targets + args), &blk)
     else
-      @func.call(op, *(@obj + args))
+      @function.call(op, *(@targets + args))
     end
   end
 
-  def instance_objects
-    return obj
-  end
+  def instance_targets ; @targets ; end
+  def instance_objects ; @targets ; end  # deprecate?
+  def instance_function; @function ; end
 
 end
 

data/lib/facets/more/multiton.rb

@@ -80,8 +80,8 @@
 # A limitation of this approach is that it is impossible to
 # detect if different blocks were given to a contructor (if it takes a
 # block).  So it is the constructor arguments _only_ which determine
-# the uniqueness of an object. A workaround is for the class to define
-# the _class_ method ::multiton_id.
+# the uniqueness of an object. To workaround this, define the _class_
+# method ::multiton_id.
 #
 #   def Klass.multiton_id(*args, &block)
 #     # ...
@@ -98,13 +98,13 @@
 
 module Multiton
 
-  # pools of objects cached on class type
+  # Pools of objects cached on class type.
   POOLS = {}
 
-  # method which can be defined by a class to determine object uniqueness
+  # Method which can be defined by a class to determine object uniqueness.
   MULTITON_ID_HOOK = :multiton_id
 
-  # method which can be defined by a class to create multiton objects 
+  # Method which can be defined by a class to create multiton objects.
   MULTITON_NEW_HOOK = :multiton_new
 
   def self.append_features( klass )

data/lib/facets/more/progressbar.rb

@@ -14,6 +14,12 @@
 #
 # Console::ProgressBar is a terminal-based progress bar library.
 #
+# == Usage
+# 
+#   pbar = ConsoleProgressBar.new( "Demo", 100 )
+#   100.times { pbar.inc }
+#   pbar.finish
+# 
 # == Author(s)
 #
 # * Satoru Takabayashi
@@ -24,7 +30,7 @@ module Console ; end
 
 class Console::ProgressBar
 
-  def initialize (title, total, out = STDERR)
+  def initialize(title, total, out = STDERR)
     @title = title
     @total = total
     @out = out

data/lib/facets/more/rexmlbuilder.rb

@@ -0,0 +1,104 @@
+#--
+# XmlBuilder
+# Copyright (c) 2006 Thomas Sawyer
+#
+# Ruby License
+#
+#++
+
+require 'rexml/document'
+require 'facets/more/builderobject'
+
+# :title: REXMLBuilder
+#
+# Build XML Documents programatically with Ruby and REXML
+# via the Builder Pattern --made possible by Ruby's blocks.
+#
+# XmlBuilder uses REXML to contruct XML documents, helping to ensure
+# XML specification conforamcy.
+#
+# == Usage
+#
+#   x = REXMLBuilder.new
+#
+#   favs = [ 'cake', 'jelly', 'salt' ]
+#
+#   x.table( :width=>'100%' ) {
+#     x.tr {
+#       favs.each { |v| x.td v }
+#       }
+#     }
+#   }
+#
+# You can also setup the XmlBuilder to assume an implicit self,
+# so the explict reciever is not needed.
+#
+#   x = REXMLBuilder.new( :implicit )
+#
+#   x.table( :width=>'100%' ) {
+#     tr {
+#         td "1" ; td "2" ; td "3"
+#       }
+#     }
+#   }
+#
+# Implict building is more elegant in form, but it is not as
+# functional because it makes it more difficult to refer to
+# external values, ie. if 'favs' were used as in the previous
+# example, it would be interpreted as another tag entry, not
+# the array.
+#
+
+class REXMLBuilder < BuilderObject
+
+  builder_include BuilderObject::REXML
+
+  # Output XML document.
+
+  def to_s( indent=nil )
+    o = ""
+    @target.write( o, indent || @options[:indent] || 0 )
+    o
+  end
+
+  # Reroute to output.
+
+  def method_missing( tag, *args, &block )
+    tag = tag.to_s
+    if tag[-1,1] == '?'
+      raise ArgumentError if block_given?
+      out.instruct( tag.chomp('?'), *args )
+    elsif tag[-1,1] == '!'
+      out.declare( tag.chomp('!'), *args )
+    else
+      out.element( tag, *args )
+    end
+    super
+  end
+
+end
+
+
+
+# TODO
+
+#=begin
+
+x = REXMLBuilder.new( :version => '1.0' )
+
+x.html {
+  x.head { x.title "Test Document" }
+  x.body( "try me" ){
+    x.out.text "No more!"
+    x.r? "x"
+    x.img :src=>"smile.jp"
+    x.h1 "Try Me"
+    x.h2 "This is a test."
+    x.div { x.span "Try" }
+    x.out "<jump>one</jump>"
+  }
+}
+
+puts x
+
+#=end

data/lib/facets/more/tuple.rb

@@ -1,6 +1,5 @@
 #--
 # Tuple
-#
 # Copyright (c) 2005 Thomas Sawyer
 #
 # Ruby License
@@ -16,6 +15,10 @@
 #  Revision History:
 # ==========================================================================
 #
+#  2006-04-10 trans
+#    Made thread safe (I hope) by using Multiton; No longer subclass
+#    of Array; and improved generally.
+#
 #  2005-11-16 trans
 #    Improved comparison operators to convert non-tuple parameters
 #    into Tuples.
@@ -29,16 +32,22 @@
 #
 # ==========================================================================
 #
-#  TODO: Thead Safety/Improve multiton.
+# TODO The #hash method needs a touch-up.
+#
+# TODO There are a few more methods yet to borrow from Array.
+#      Consider how #+, #-, etc. ought to work.
 #
 #++
 
+require 'facets/more/multiton'
+
 #:title: Tuple
 #
-# A Tuple is essentially an Array that is Multiton and Comaparable.
-# A Tuple can be made using #[] as one builds an array, or
-# using the #new method passing in an array or a string parameters
-# with elements divided by any non-alphanumeric character.
+# Tuple is essentially an Array, but Comaparable and Immutable.
+#
+# A tuple can be made using #new or #[] just as one builds an array,
+# or using the #to_t method on a string or array. With a string tuple
+# remembers the first non-alphanumeric character as the tuple divider.
 #
 # == Usage
 #
@@ -48,30 +57,128 @@
 #   t1 < t2   #=> true
 #   t1 > t2   #=> false
 #
-#   t1 = Tuple.new('1.2.3')
-#   t2 = Tuple.new('1-2-3')
+#   t1 = '1.2.3'.to_t
+#   t2 = '1-2-3'.to_t
+#
+#   puts t1  #=> 1.2.3
+#   puts t2  #=> 1-2-3
 #
 #   t1 == t2  #=> true
 #
+# Keep in mind that Tuple[1,2,3] is not the same as Tuple['1','2','3'].
+#
 # == Author(s)
 #
 # * Thomas Sawyer
 #
 
-class ::Tuple < ::Array
+class ::Tuple
 
+  include ::Multiton
+  include ::Enumerable
   include ::Comparable
 
-  def initialize(args, divider=nil)
-    super()
-    @divider = divider || ':'
-    self.concat args
+  def self.multiton_id(arg=0, default=0, &block)
+    if block_given?
+      values = []
+      arg.times { |i| values << block[i] }
+    elseif Integer === arg
+      values = [ default ] * arg
+    else
+      values = arg.to_ary
+    end
+    values
+  end
+
+  def initialize(arg=0, default=0, &blk)
+    if block_given?
+      @values = []
+      arg.times { |i| @values << blk[i] }
+    elseif Integer === arg
+      @values = [ default ] * arg
+    else
+      @values = arg.to_ary
+    end
+    @default = default
+    @divider = '.'
+  end
+
+  attr_accessor :default, :divider
+
+protected
+
+  def values() @values end
+
+public
+
+  def inspect() to_a.inspect end
+
+  def to_t()     self end
+  def to_tuple() self end
+
+  def to_a()   Array(@values) end
+  def to_ary() Array(@values) end
+
+  def to_s( divider=nil )
+    @values.join(divider||@divider)
+  end
+
+  def size()   @values.size end
+  def length() @values.size end
+
+  def empty?()
+    return true if @values.empty?
+    return true if @values == [ @default ] * @values.size
+    false
+  end
+
+  def each( &block )
+    @values.each( &block )
+  end
+
+  def each_index( &block )
+    @values.each_index( &block )
+  end
+
+  def [](i)
+    @values.fetch(i,@default)
+  end
+
+  def []=(i,v)
+    @values[i] = v
+  end
+
+  def index()  @values.index end
+  def rindex() @values.rindex end
+
+  # Unlike Array, Tuple#<< cannot act in place
+  # becuase Tuple's are immutable.
+  def <<( obj )
+    self.class.new( to_a << obj )
   end
 
-  def to_s ; join(@divider) ; end
+  def pop() Tuple.new( to_a.pop ) end
+  def push( obj ) Tuple.new( to_a.push(obj) ) end
+  def pull() Tuple.new( to_a.shift ) end
+  def pot( obj ) Tuple.new( to_a.unshift(obj) ) end
+  alias_method :unshift, :pot
+  alias_method :shift, :pull
+
+  # Returns true if two tuple references are for the
+  # very same tuple.
+  def eql?( other )
+    return true if object_id == other.object_id
+    #return true if values.eql? other.values
+  end
 
-  def to_t ; self ; end
-  def to_tuple ; self ; end
+  def <=>( other )
+    other = other.to_t
+    [size, other.size].max.times do |i|
+      c = self[i] <=> other[i]
+      return c if c != 0
+    end
+    0
+  end
 
   # For pessimistic constraint (like '~>' in gems)
   def =~( other )
@@ -81,60 +188,93 @@ class ::Tuple < ::Array
     self >= other and self < upver
   end
 
-  def ==( other ) ; super( other.to_t ) ; end
-  def  >( other ) ; super( other.to_t ) ; end
-  def  <( other ) ; super( other.to_t ) ; end
-  def >=( other ) ; super( other.to_t ) ; end
-  def <=( other ) ; super( other.to_t ) ; end
+  def first() @values.first end
+  def last()  @values.last end
 
-  # class-level -----------------------------------------------
+  # These are useful for using a Tuple as a version.
+  def major() @values.first end
+  def minor() @values.at(1) end
+  def teeny() @values.at(2) end
+
+  # Unique hash value.
+  def hash
+    # TODO This needs to take into account the default
+    #      and maybe the divider too.
+    to_a.hash
+  end
 
-  @tuples = {}
+  # class-level -----------------------------------------------
 
   class << self
 
-    alias_method :instance, :new
+    def []( *args )
+      new( args )
+    end
+
+    #
 
-    def new( arg )
-      case arg
-      when Array, Tuple
-        div = nil
-      else
-        div = /\W/.match(arg)[0]
-        args = arg.to_s.split(/\W/).collect { |e| e.to_i }
+    def cast_from_string( str ) # :yield:
+      args = str.to_s.split(/\W/)
+      div = /\W/.match( str.to_s )[0]
+      if block_given?
+        args = args.collect{ |a| yld[a] }
       end
-      @tuples[args] ||= instance(args, div)
+      t = self.new( args )
+      t.divider = div
+      t
     end
 
-    def []( *args )
-      @tuples[args] ||= instance(args)
+    def cast_from_array( arr )
+      self.new( arr )
     end
 
-    # Parses a constraint returning the operation, and the
-    # tuple to compare against.
-    def decipher_constraint( constraint )
-      if md = %r{^(=~|~>|<=|>=|==|=|<|>)(.*)$}.match( constraint.strip )
-        opr = md[1]
-        opr = '=~' if opr == '~>'
-        opr = '==' if opr == '='
-        val = instance(md[2])
+    # Parses a constraint returning the operation as a lambda.
+
+    def parse_constraint( constraint )
+      constraint = constraint.strip
+      re = %r{^(=~|~>|<=|>=|==|=|<|>)?(\d+(:?[-.]\d+)*)$}
+      if md = re.match( constraint )
+        if op = md[1]
+          op = '=~' if op == '~>'
+          op = '==' if op == '='
+          val = new( md[2] )
+        else
+          op = '=='
+          val = new( constraint )
+        end
       else
-        opr = '=='
-        val = instance(constraint.strip)
+        raise ArgumentError, "invalid constraint"
       end
-      return opr, val
+      return op, val
+    end
+
+    def constraint_to_lambda( constraint )
+      op, val = *parse_constraint( constraint )
+      lambda { |t| t.send(op, val) }
     end
 
-  end #class << self
+  end
 
 end
 
+
 # Conveniently turn a string into a tuple.
 
 class ::String
 
+  def to_t( &yld )
+    Tuple.cast_from_string( self, &yld )
+  end
+
+end
+
+
+# Convert and array into a tuple.
+
+class ::Array
+
   def to_t
-    ::Tuple.new(self)
+    Tuple.cast_from_array( self )
   end
 
 end
@@ -148,20 +288,44 @@ end
 #   |_|\___||___/\__|
 #
 
-=begin test
+=begin testing
 
   require 'test/unit'
 
-  class TC_Tuple < Test::Unit::TestCase 
+  class TC_Tuple < Test::Unit::TestCase
+
+    def test_01
+      t1 = Tuple[1,2,3]
+      t2 = Tuple[2,4,5]
+      assert( t1 < t2 )
+      assert( t2 > t1 )
+    end
+
+    def test_02
+      t1 = Tuple[1,2,3]
+      a1 = t1.to_a
+      assert( Array === a1 )
+    end
+
+    def test_03
+      t1 = Tuple[1,2,3]
+      t2 = Tuple[1,2,3]
+      assert( t1.object_id === t2.object_id )
+    end
 
-    def setup
-      @t1 = Tuple[1,2,3]
-      @t2 = Tuple[2,4,5]
+    def test_04
+      t1 = Tuple[1,2,3]
+      t1 = t1 << 4
+      assert( Tuple === t1 )
+      t2 = Tuple[1,2,3,4]
+      assert( t1.object_id == t2.object_id )
     end
 
-    def test_compare
-      assert( @t1 < @t2 )
-      assert( @t2 > @t1 )
+    def test_05
+      t1 = "1.2.3".to_t
+      assert( Tuple === t1 )
+      t2 = Tuple['1','2','3']
+      assert( t1.object_id == t2.object_id )
     end
 
   end