cheri 0.0.2

data/lib/cheri/builder/awt/main.rb

@@ -0,0 +1,191 @@
+#--
+# Copyright (C) 2007 William N Dortch <bill.dortch@gmail.com>
+#
+# 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.
+#++
+#
+
+
+module Cheri
+# TODO: module comments
+module AWT
+VERSION = Cheri::VERSION
+
+include Cheri::Builder
+
+CJava = Cheri::Java #:nodoc:
+CBuilder = Cheri::Builder #:nodoc:
+JBuilder = Cheri::Java::Builder #:nodoc:
+class << self
+  def append_features(clazz)
+    CBuilder.module_included(JBuilder,clazz)
+    CBuilder.module_included(self,clazz)
+    super
+  end
+  private :append_features
+  
+  def factory
+    AWTFactory  
+  end
+  
+  def connecter
+    AWTConnecter  
+  end
+
+  def consumer
+    AWTConsumer
+  end
+  
+  def resolver
+    AWTResolver  
+  end
+
+  # call-seq:
+  #   mod.prepare(context, parent, object, sym, properties=nil) -> prepared?
+  # 
+#  def prepare(*r)
+#    AWTConnecter.prepare(*r)
+#  end
+  
+end #self
+
+
+  # call-seq:
+  #   awt([*args] [, &block]) -> AWTProxy if no block given, else result of block
+  #   
+  def awt(*r,&k)
+    if (ctx = __cheri_ctx)
+      if k
+        AWTFrame.new(ctx,*r,&k).run
+      else
+        ctx[:awt_proxy] ||= AWTProxy.new(ctx,*r)
+      end
+    end
+  end
+  private :awt
+
+
+class AWTClassBuilder < Cheri::Java::Builder::ClassBuilder
+Frame = CJava.get_class('java.awt.Frame')
+  def mod
+    Cheri::AWT  
+  end
+private
+  def post
+    @obj.icon_image ||= CJava.cheri_icon.image if @obj.kind_of?(Frame)
+  end
+end
+
+module StandardFactory
+  T = Cheri::AWT::Types #:nodoc:
+  def self.builder(ctx,sym,*r,&k)
+    clazz = T.get_class(sym)
+    clazz ? AWTClassBuilder.new(ctx,sym,clazz,*r,&k) : nil
+  end
+end #AWTFactory
+
+AWTFactory = Cheri::Builder::SuperFactory.new do |f|
+  f << StandardFactory
+  f << Cheri::Java::Builder::CheriYieldFactory
+  f << Cheri::Java::Builder::CherifyFactory
+  f << Cheri::Builder::CheriYieldFactory
+  f << Cheri::Builder::CherifyFactory
+end
+
+class AWTProxy < Cheri::Builder::BaseProxy
+
+  impl(Types.names)
+
+  def initialize(ctx,*r)
+    super
+    if Hash === r.last
+      @ctx.auto!(mod) if r.last[:auto]
+    end  
+  end
+
+  def mod
+    Cheri::AWT  
+  end
+  private :mod
+
+  def [](opts)
+    raise Cheri.type_error(opts,Hash) unless Hash === opts
+    if opts[:auto]
+      @ctx.ictx.auto!(mod)
+      @ctx.auto!(mod)
+    end
+    self
+  end
+end #AWTProxy
+
+class AWTFrame
+  include Cheri::Builder::Frame
+  def initialize(ctx,*r,&k)
+    super
+    @obj = ctx[:awt_proxy] ||= AWTProxy.new(ctx,*r)  
+  end
+  def mod
+    Cheri::AWT  
+  end
+end #AWTFrame
+
+module SizeMethodConsumer
+#:stopdoc:
+Meths = {
+  :minimum_size => :minimum_size=,
+  :set_minimum_size => :minimum_size=,
+  :maximum_size => :maximum_size=,
+  :set_maximum_size => :maximum_size=,
+  :preferred_size => :preferred_size=,
+  :set_preferred_size => :preferred_size=,
+  :fixed_size => true
+}.freeze
+Cmp = ::Java::JavaAwt::Component
+Dim = ::Java::JavaAwt::Dimension
+#:startdoc:
+  def self.consume(ctx,bld,sym,*args,&block)
+    return false,nil unless (meth = Meths[sym]) && args.length == 2 && 
+      Cmp === (obj = bld.object) && Fixnum === (w = args[0]) && Fixnum === (h = args[1])
+    dim = Dim.new w,h
+    if :fixed_size == sym
+      obj.minimum_size = dim
+      obj.maximum_size = dim
+      obj.preferred_size = dim
+    else
+      obj.__send__(meth,dim)
+    end
+    return true, nil
+  end
+end
+
+AWTConsumer = Cheri::Builder::SuperConsumer.new do |c|
+  c << SizeMethodConsumer
+  c << Cheri::Java::Builder::EventMethodConsumer
+  c << Cheri::Java::Builder::GenericConsumer
+  c << Cheri::Builder::DefaultConsumer
+end
+
+AWTResolver = Cheri::Java::Builder::ConstantResolver.new do |r|
+  r << Constants
+end
+
+
+end #AWT
+end #Cheri

data/lib/cheri/builder/awt/types.rb

@@ -0,0 +1,220 @@
+#--
+# Copyright (C) 2007 William N Dortch <bill.dortch@gmail.com>
+#
+# 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.
+#++
+#
+
+
+module Cheri
+module AWT
+module Types
+CJava = Cheri::Java
+JA = 'java.awt.'.freeze
+class << self
+  def get_class(y)
+    # TODO: threadsafe support? Probably not necessary if we're not adding keys.
+    c = @classes[y]
+    if c
+      if c.instance_of?(String)
+        c = CJava.get_class(JA + c)
+        @classes[y] = c if c
+      end
+      c
+    else
+      nil
+    end
+  end
+  def names
+    @names ||= @classes.keys
+  end
+end #self
+# TODO: review included classes; some of these would
+# never be called in a builder context
+@classes = {
+  :alpha_composite => 'AlphaComposite',
+  :awt_event => 'AWTEvent',
+  :awt_event_multicaster => 'AWTEventMulticaster',
+  :awt_key_stroke => 'AWTKeyStroke',
+  :awt_permission => 'AWTPermission',
+  :basic_stroke => 'BasicStroke',
+  :border_layout => 'BorderLayout',
+  :buffer_capabilities => 'BufferCapabilities',
+  :buffer_capabilities_flip_contents => 'BufferCapabilities::FlipContents',
+  :button => 'Button',
+  :canvas => 'Canvas',
+  :card_layout => 'CardLayout',
+  :checkbox => 'Checkbox',
+  :checkbox_group => 'CheckboxGroup',
+  :checkbox_menu_item => 'CheckboxMenuItem',
+  :choice => 'Choice',
+  :color => 'Color',
+  :component => 'Component',
+  :component_orientation => 'ComponentOrientation',
+  :container => 'Container',
+  :container_order_focus_traversal_policy => 'ContainerOrderFocusTraversalPolicy',
+  :cursor => 'Cursor',
+  :default_focus_traversal_policy => 'DefaultFocusTraversalPolicy',
+  :default_keyboard_focus_manager => 'DefaultKeyboardFocusManager',
+  :desktop => 'Desktop',
+  :dialog => 'Dialog',
+  :dimension => 'Dimension',
+  :display_mode => 'DisplayMode',
+  :event => 'Event',
+  :event_queue => 'EventQueue',
+  :file_dialog => 'FileDialog',
+  :flow_layout => 'FlowLayout',
+  :focus_traversal_policy => 'FocusTraversalPolicy',
+  :font => 'Font',
+  :font_metrics => 'FontMetrics',
+  :frame => 'Frame',
+  :gradient_paint => 'GradientPaint',
+  :graphics => 'Graphics',
+  :graphics_2d => 'Graphics2D',
+  :graphics_config_template => 'GraphicsConfigTemplate',
+  :graphics_configuration => 'GraphicsConfiguration',
+  :graphics_device => 'GraphicsDevice',
+  :graphics_environment => 'GraphicsEnvironment',
+  :grid_bag_constraints => 'GridBagConstraints',
+  :grid_bag_layout => 'GridBagLayout',
+  :grid_bag_layout_info => 'GridBagLayoutInfo',
+  :grid_layout => 'GridLayout',
+  :image => 'Image',
+  :image_capabilities => 'ImageCapabilities',
+  :insets => 'Insets',
+  :job_attributes => 'JobAttributes',
+  :keyboard_focus_manager => 'KeyboardFocusManager',
+  :label => 'Label',
+  :linear_gradient_paint => 'LinearGradientPaint',
+  :list => 'List',
+  :media_tracker => 'MediaTracker',
+  :menu => 'Menu',
+  :menu_bar => 'MenuBar',
+  :menu_component => 'MenuComponent',
+  :menu_item => 'MenuItem',
+  :menu_shortcut => 'MenuShortcut',
+  :mouse_info => 'MouseInfo',
+  :multiple_gradient_paint => 'MultipleGradientPaint',
+  :page_attributes => 'PageAttributes',
+  :panel => 'Panel',
+  :point => 'Point',
+  :pointer_info => 'PointerInfo',
+  :polygon => 'Polygon',
+  :popup_menu => 'PopupMenu',
+  :print_job => 'PrintJob',
+  :radial_gradient_paint => 'RadialGradientPaint',
+  :rectangle => 'Rectangle',
+  :rendering_hints => 'RenderingHints',
+  :rendering_hints_key => 'RenderingHints::Key',
+  :robot => 'Robot',
+  :scrollbar => 'Scrollbar',
+  :scroll_pane => 'ScrollPane',
+  :scroll_pane_adjustable => 'ScrollPaneAdjustable',
+  :splash_screen => 'SplashScreen',
+  :system_color => 'SystemColor',
+  :system_tray => 'SystemTray',
+  :text_area => 'TextArea',
+  :text_component => 'TextComponent',
+  :text_field => 'TextField',
+  :texture_paint => 'TexturePaint',
+  :toolkit => 'Toolkit',
+  :tray_icon => 'TrayIcon',
+  :window => 'Window',
+  :clipboard => 'datatransfer.Clipboard',
+  :data_flavor => 'datatransfer.DataFlavor',
+  :flavor_event => 'datatransfer.FlavorEvent',
+  :string_selection => 'datatransfer.StringSelection',
+  :affine_transform => 'geom.AffineTransform',
+  :arc_2d_double => 'geom.Arc2D::Double',
+  :arc_2d_float => 'geom.Arc2D::Float',
+  :area => 'geom.Area ',
+  :cubic_curve_2d_double => 'geom.CubicCurve2D::Double',
+  :cubic_curve_2d_float => 'geom.CubicCurve2D::Float',
+  :ellipse_2d_double => 'geom.Ellipse2D::Double',
+  :ellipse_2d_float => 'geom.Ellipse2D::Float',
+  :flattening_path_iterator => 'geom.FlatteningPathIterator',
+  :general_path => 'geom.GeneralPath',
+  :line_2d_double => 'geom.Line2D::Double',
+  :line_2d_float => 'geom.Line2D::Float',
+  :path_2d_double => 'geom.Path2D::Double',
+  :path_2d_float => 'geom.Path2D::Float',
+  :point_2d_double => 'geom.Point2D::Double',
+  :point_2d_float => 'geom.Point2D::Float',
+  :quad_curve_2d_double => 'geom.QuadCurve2D::Double',
+  :quad_curve_2d_float => 'geom.QuadCurve2D::Float',
+  :rectangle_2d_double => 'geom.Rectangle2D::Double',
+  :rectangle_2d_float => 'geom.Rectangle2D::Float',
+  :round_rectangle_2d_double => 'geom.RoundRectangle2D::Double',
+  :round_rectangle_2d_float => 'geom.RoundRectangle2D::Float',
+  :affine_transform_op => 'image.AffineTransformOp',
+  :area_averaging_scale_filter => 'image.AreaAveragingScaleFilter',
+  :band_combine_op => 'image.BandCombineOp',
+  :banded_sample_model => 'image.BandedSampleModel',
+  :buffered_image => 'image.BufferedImage',
+  :buffered_image_filter => 'image.BufferedImageFilter',
+  :buffer_strategy => 'image.BufferStrategy',
+  :byte_lookup_table => 'image.ByteLookupTable',
+  :color_convert_op => 'image.ColorConvertOp',
+  :color_model => 'image.ColorModel',
+  :component_color_model => 'image.ComponentColorModel',
+  :component_sample_model => 'image.ComponentSampleModel',
+  :convolve_op => 'image.ConvolveOp',
+  :crop_image_filter => 'image.CropImageFilter',
+  :data_buffer => 'image.DataBuffer',
+  :data_buffer_byte => 'image.DataBufferByte',
+  :data_buffer_double => 'image.DataBufferDouble',
+  :data_buffer_float => 'image.DataBufferFloat',
+  :data_buffer_int => 'image.DataBufferInt',
+  :data_buffer_short => 'image.DataBufferShort',
+  :data_buffer_ushort => 'image.DataBufferUShort',
+  :direct_color_model => 'image.DirectColorModel',
+  :filtered_image_source => 'image.FilteredImageSource',
+  :image_filter => 'image.ImageFilter',
+  :index_color_model => 'image.IndexColorModel',
+  :kernel => 'image.Kernel',
+  :lookup_op => 'image.LookupOp',
+  :lookup_table => 'image.LookupTable',
+  :memory_image_source => 'image.MemoryImageSource',
+  :multi_pixel_packed_sample_model => 'image.MultiPixelPackedSampleModel',
+  :packed_color_model => 'image.PackedColorModel',
+  :pixel_grabber => 'image.PixelGrabber',
+  :pixel_interleaved_sample_model => 'image.PixelInterleavedSampleModel',
+  :raster => 'image.Raster',
+  :replicate_scale_filter => 'image.ReplicateScaleFilter',
+  :rescale_op => 'image.RescaleOp',
+  :rgb_image_filter => 'image.RGBImageFilter',
+  :rgb_image_filter => 'image.RGBImageFilter',
+  :sample_model => 'image.SampleModel',
+  :short_lookup_table => 'image.ShortLookupTable',
+  :single_pixel_packed_sample_model => 'image.SinglePixelPackedSampleModel',
+  :volatile_image => 'image.VolatileImage ',
+  :writable_raster => 'image.WritableRaster',
+  :parameter_block => 'image.renderable.ParameterBlock',
+  :renderable_image_op => 'image.renderable.RenderableImageOp',
+  :renderable_image_producer => 'image.renderable.RenderableImageProducer',
+  :render_context => 'image.renderable.RenderContext',
+}  
+
+end #Types
+end #AWT
+end #Cheri
+
+#cls = Cheri::AWT::Types.get_class(:frame)
+#puts cls.java_class.name

data/lib/cheri/builder/base.rb

@@ -0,0 +1,533 @@
+#--
+# Copyright (C) 2007 William N Dortch <bill.dortch@gmail.com>
+#
+# 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.
+#++
+#
+
+module Cheri
+module Builder
+
+# Frame contains default implementations of the methods required by objects that
+# will be pushed onto the Cheri::Builder::Context stack.  Note that concrete
+# builders will need to override some of these methods, such as #mod, #parent? 
+# and #child?.
+#
+# Frame is provided as a convenience; its use is not required.
+#
+# If used, Frame should normally be included before other Cheri::Builder convenience
+# modules (such as Content or Attributes). Classes/modules that include it should
+# be sure to call super from their initialize methods, if any.
+module Frame
+  # Stores the context and block (if any) in @ctx and @blk.
+  def initialize(ctx,*args,&blk) #:doc:
+    @ctx = ctx
+    @blk = blk if blk
+    super(*args)
+  end
+  
+  # Returns @ctx, the Context instance to which this frame belongs.
+  def ctx
+    @ctx  
+  end
+  alias_method :context, :ctx
+
+  # Returns @blk, the block passed to this frame, if any.
+  def block
+    @blk
+  end
+
+  # Perform whatever actions are required to build +object+. Normally overridden to 
+  # create +object+ and call its block, if any.  Should return the built object.
+  # 
+  # The default implementation simply calls +block+, if present. (Note that the block
+  # is actually called indirectly, via Cheri::Builder::Context#call, which manages
+  # the stack and connections. You normally do _not_ want to call the block directly.)
+  def run
+    @ctx.call(self,&@blk) if @blk
+  end
+
+  # The object for this frame (builder). Normally the object being built, once it has
+  # been created. May be the same as the builder object (see Cheri::Html::Elem, for example).
+  def object
+    @obj
+  end
+  
+  # The builder module (such as Cheri::Swing) associated with this frame (builder object).
+  # Normally must be overridden. Default: Cheri::Builder::CheriModule
+  def mod
+    CheriModule  
+  end
+
+  # Override to return +true+ if +object+ can be a parent of other objects. Default: +false+
+  def parent?
+    false
+  end
+
+  # Override to return +true+ if +object+ can be a child of another object. Default: +false+
+  def child?
+    false
+  end
+  
+  # Override to return +true+ if +object+ wants the opportunity to connect to any object
+  # created in the hierarchy below it. Normally used by non-structural components (Swing's
+  # ButtonGroup, for example). Adds build overhead, so use sparingly.
+  def any?
+    false
+  end
+     
+  # Overrides the default Object#inspect to prevent mind-boggling circular displays in IRB.
+  def inspect
+    "#<#{self.class}:instance>"  
+  end
+
+end #Frame
+
+module Parent
+  def parent?
+    true
+  end
+end
+
+module Child
+  def child?
+    true  
+  end
+end
+
+# Builder extends the functionality of Frame, extracting the symbol (+sym+) and arguments
+# (+args+) from the arguments passed by a factory.  Like Frame, it is a convenience that
+# may be included in (or otherwise used to extend) builder classes/objects.
+module Builder
+  include Frame
+  # Calls super to store context and block, then stores sym and args in @sym and @args.
+  def initialize(ctx,sym,*args,&blk) #:doc:
+    super(ctx,&blk)
+    @sym = sym
+    @args = args
+  end
+
+  # Returns the symbol passed by the factory that created this builder. The symbol
+  # normally originates in the method_missing method of the client object.
+  def sym
+    @sym
+  end
+
+  # Returns the arguments (excluding ctx and sym) passed by the factory that created
+  # this builder.
+  def args
+    @args  
+  end
+
+  def run
+    @ctx.call(self,&@blk) if @blk
+    @obj
+  end
+  
+  # Overrides Frame#parent? to return +true+.
+  def parent?
+    true  
+  end
+  
+  # Overrides Frame#child? to return +true+.
+  def child?
+    true
+  end
+end
+
+module DynamicModule
+  def initialize(mod,*r,&k)
+    @mod = mod
+    super(*r,&k)  
+  end
+  
+  def mod
+    @mod  
+  end
+end
+# An 'abstract' builder class. Includes the methods defined in Frame and Builder.
+# Provided as a convenience.
+class AbstractBuilder
+  include Builder
+end # AbstractBuilder
+
+
+# A convenience 'base' builder class.  Breaks the #run method into several steps.
+class BaseBuilder < AbstractBuilder
+
+  def run
+    pre
+    create unless @no_create
+    post
+    call unless @no_call
+    @obj
+  end
+
+  # Returns ! @not_parent
+  def parent?
+   ! @not_parent
+  end
+
+  # Returns ! @not_child 
+  def child?
+   ! @not_child  
+  end
+
+private
+  # called before object created
+  def pre #:doc:
+  end
+
+  # override to create object
+  def create #:doc:
+  end
+
+  # called after object is created
+  def post #:doc:
+  end
+
+  # called to call block unless there is no block or @no_call is set
+  def call #:doc:
+    @ctx.call(self,&@blk) if @blk
+  end
+end #BaseBuilder
+
+# Appendable types define to_s, to_str and to_io methods that take an optional
+# parameter, to which output is appended.  This is essentially a marker interface;
+# the supplied implementations do nothing useful.
+module Appendable
+  # Append value (whatever that might be) to the supplied String, or create and
+  # return a new String if none is supplied. If #esc is overridden, value will
+  # be escaped first. Delegates to #to_io unless String === str.  Note that this
+  # implementation appends an empty string; override to do something useful.
+  def to_s(str='')
+    return to_io(str) unless String === str
+    esc('',str)
+  end
+  
+  # Calls #to_s(str).  Provided so that Appendable objects may be coerced to
+  # Strings automatically, as in <tt>str << my_appendable_thingy</tt>. Implemented
+  # this way rather than through alias_method to counter the possibility that
+  # overriders of #to_s will forget to re-alias to_str.
+  def to_str(str='')
+    to_s(str)  
+  end
+
+  # Append value (whatever that might be) to the supplied output stream.  If
+  # #esc is overridden, value will be escaped first. Note that this
+  # implementation appends an empty string; override to do something useful.
+  def to_io(ios)
+    ios << esc('')
+  end
+  
+  # Override to escape values (default implementation appends or returns
+  # the input value unaltered).
+  def esc(inp,out=nil)
+    out ? out << inp : inp
+  end
+
+end
+
+# Methods to support content (primarily intended for use with XML/HTML markup).
+# See also EmptyContent, ContentArgs.
+module Content
+  include Appendable
+  
+  # Adds +value+ to the content array (@cont) for this object if #content?(+value+)
+  # returns +true+.
+  def add(value)
+    (@cont ||= []) << value if content?(value)
+    self
+  end
+  alias_method :<<, :add  
+  
+  # Returns the content array (@cont) if present, otherwise +nil+.
+  def content
+    @cont  
+  end
+  
+  # Iterates over the content array (@cont) for this object. Equivalent to
+  # calling #content#each.
+  def each #:yields: content_value
+    @cont.each do |v|
+      yield v
+    end if @cont && block_given?
+  end
+
+  # Returns truth value if +value+ is valid content for this builder/object,
+  # +false+/+nil+ otherwise.  Called by #add before adding content; +value+ will
+  # not be added unless content? is true.
+  # 
+  # This implementation always returns +true+. Override to validate each content
+  # element before it is added.  You may wish to raise an exception or issue a 
+  # warning in the case of invalid content.
+  def content?(value)
+    true
+  end
+  
+  # Appends concatenated and escaped content (@cont) to +str+, if supplied, using
+  # the +<<+ operator.  Assumes String === +str+. Use #cont_io to append to IO or Array.
+  def cont_s(str='')
+    @cont.each do |v|
+      case v
+        when String     : esc(v,str)
+        when Appendable : v.to_s(str)
+        else esc(v.to_s,str)
+      end
+    end if @cont
+    str
+  end
+  
+  # Appends concatenated and escaped content (@cont) to +ios+, if supplied, using
+  # the +<<+ operator. Use for appending to IO or Array. Use #cont_s to append more
+  # efficiently to strings.
+  def cont_io(ios)
+    @cont.each do |v|
+      case v
+        when String     : ios << esc(v)
+        when Appendable : v.to_io(ios)
+        else ios << esc(v.to_s)
+      end
+    end if @cont
+    ios
+  end
+    
+  # Override to escape values by appending the escaped +inp+ value to output
+  # string +out+ (using << or concat). If +out+ is nil, just return the escaped
+  # string. The default implementation appends or returns the input value unaltered.
+  def esc(inp,out=nil)
+    out ? out << inp : inp
+  end
+
+end
+
+# Methods to support attributes (primarily intended for use with XML/HTML markup).
+# Note: include before ContentArgs if both are being included.
+module Attributes
+  include Appendable
+  #:stopdoc:
+  S = ' '.freeze
+  Q = '"'.freeze
+  E = '='.freeze
+  #:startdoc:
+  def initialize(*r,&k)
+    super
+    if @args && Hash === @args.last
+      @args.pop.each_pair do |n,v| add_attr(n,v); end
+    end
+  end
+
+  # Returns the attibutes hash (@attrs), if any.
+  def attrs
+    @attrs  
+  end
+  
+  # Add an attribute. Called by #initialize to add/validate attributes passed as
+  # arguments.
+  def add_attr(name,value)
+    (@attrs ||= {})[name] = value if attr?(name,value)
+  end
+
+  # Override to validate each attribute before it is added. The default
+  # implementation accepts any name/value.
+  def attr?(name,value)
+    true
+  end
+
+  # Writes attributes to a new string, or appends to an existing string
+  # (using <<) if supplied.
+  def attr_s(str='')
+    @attrs.each_pair do |k,v|
+      str << 32 << k.to_s << ?= << 34 << v.to_s << 34
+    end if @attrs
+    str
+  end
+  
+  # Writes attributes to the supplied IO stream (or Array, etc.) using <<.
+  def attr_io(ios)
+    @attrs.each_pair do |k,v|
+      ios << S << k << E << Q << v << Q
+    end if @attrs
+    ios
+  end
+end
+
+# Calls +add+ to add each argument passed to new/initialize. Use with Content
+# module if content values will be passed as arguments.  Note: include after
+# Attributes if both are being used.
+module ContentArgs
+  def initialize(*r,&k)
+    super
+    @args.each do |a| add a; end
+  end
+end #ContentArgs
+
+
+# Methods to support empty content models (primarily intended for use with XML/HTML markup).
+# See also Content, ContentArgs.
+module EmptyContent
+  include Appendable
+  CE = ' />'.freeze #:nodoc:
+
+  # Returns +false+
+  def content?(value)
+    false  
+  end
+  
+  def empty_s(str='')
+    str << CE
+  end
+
+  def empty_io(ios)
+    ios << CE
+  end
+
+end #EmptyContent
+
+module MarkupWriter
+  #:stopdoc:
+  C = '</'.freeze
+  E = '>'.freeze
+  EC = '></'.freeze
+  O = '<'.freeze
+  #:startdoc:
+
+  # Append this markup to +str+ (or an empty string if +str+ is not supplied),
+  # and return the result.  Redirects to #to_io if +str+ is not a String.  Both
+  # methods use the +<<+ operator to append their output; this method (like the other
+  # ..._s methods) is faster because Fixnum values can be appended directly, without
+  # being converted to (or passed as) strings. This takes on particular significance
+  # when output is being escaped, and values passed one character at a time.
+  def to_s(str='')
+    return to_io(str) unless String === str
+    open_s(str)
+    attr_s(str) if @attrs
+    if @cont
+      str << ?>
+      cont_s(str)
+      close_s(str)
+    else
+      empty_s(str)
+    end
+    str
+  end
+  
+  # Append this markup to +ios+
+  def to_io(ios)
+    open_io(ios)  
+    attr_io(ios) if @attrs
+    if @cont
+      ios << E
+      cont_io(ios)
+      close_io(ios)
+    else
+      empty_io(ios)
+    end
+    ios
+  end
+
+  # Append open tag (<tagname) to +str+ using +<<+.
+  def open_s(str)
+    str << ?< << (@tag ||= @sym.to_s)
+  end
+  
+  # Append open tag (<tagname) to +ios+ using +<<+.
+  def open_io(ios)
+    ios << O << (@tag ||= @sym.to_s)
+  end
+  
+  # Append close tag (</tagname>) to +str+ using +<<+.
+  def close_s(str)
+    str << C << @tag << ?>
+  end
+  
+  # Append close tag (</tagname>) to +ios+ using +<<+.  (Use slightly faster
+  # #close_s for strings.)
+  def close_io(ios)
+    ios << C << @tag << E  
+  end
+  
+  # Append empty close tag (...></tagname>) to +str+. Note that HTML/XML elements
+  # with empty content models should close with <tt>' />'</tt> instead (see EmptyContent).
+  def empty_s(str)
+    str << EC << @tag << ?>
+  end
+  
+  # Append empty close tag (...></tagname>) to +ios+. Note that HTML/XML elements
+  # with empty content models should close with <tt>' />'</tt> instead (see EmptyContent).
+  def empty_io(ios)
+    ios << EC << @tag << E
+  end
+  
+end #MarkupWriter
+
+module Markup
+  include Content
+  include Attributes
+  include ContentArgs
+  include MarkupWriter
+end #Markup
+
+module EmptyMarkup
+  # We include Content and ContentArgs so that warnings/exceptions may be
+  # issued (by overriding #add or #content?) if the user attempts to add to this element.
+  # Otherwise, unconnectable elements would simply be ignored.
+  include Markup
+#  include Content
+#  include Attributes
+#  include ContentArgs
+#  include MarkupWriter
+  include EmptyContent
+end #EmptyMarkup
+
+module MarkupBuilder
+  include Builder
+  include Markup
+  
+  def object
+    self  
+  end
+
+  def run
+    value = @ctx.call(self,&@blk) if @blk
+    add(value) if String === value
+    self
+  end
+end #MarkupBuilder
+
+module EmptyMarkupBuilder
+  include Builder
+  include EmptyMarkup
+  
+  def object
+    self  
+  end
+  
+  def run
+    value = @ctx.call(self,&@blk) if @blk
+    # of course we want this to then fail in #add / #content?  e.g., see Cheri::Html::EmptyElem
+    add(value) if String === value
+    self
+  end
+
+end #EmptyMarkupBuilder
+
+end #Builder
+end #Cheri