clarion-builder 1.0.0

data/doc/releases/builder-1.2.4.rdoc

@@ -0,0 +1,31 @@
+= Builder 1.2.4 Released.
+
+Added a "CDATA" method to the XML Markup builder (from Josh Knowles).
+
+== What is Builder?
+
+Builder::XmlMarkup allows easy programmatic creation of XML markup.
+For example:
+
+  builder = Builder::XmlMarkup.new(:target=>STDOUT, :indent=>2)
+  builder.person { |b| b.name("Jim"); b.phone("555-1234") }
+  puts builder.target!
+
+will generate:
+
+  <person>
+    <name>Jim</name>
+    <phone>555-1234</phone>
+  </person>
+
+== Availability
+
+The easiest way to get and install builder is via RubyGems ...
+
+  gem install builder    (you may need root/admin privileges)
+
+== Thanks
+
+* Josh Knowles for the cdata! patch.
+
+-- Jim Weirich

data/doc/releases/builder-2.0.0.rdoc

@@ -0,0 +1,46 @@
+= Builder 2.0.0 Released.
+
+== Changes in 2.0.0
+
+* UTF-8 characters in data are now correctly translated to their XML
+  equivalents. (Thanks to Sam Ruby)
+
+* Attribute values are now escaped by default.  See the README
+  file for details.
+
+<b>NOTE:</b> The escaping attribute values by default is different
+than in previous releases of Builder.  This makes version 2.0.0
+somewhat incompatible with the 1.x series of Builder.  If you use "&",
+"<", or ">" in attributes values, you may have to change your
+code. (Essentially you remove the manual escaping.  The new way is
+easier, believe me).
+
+== What is Builder?
+
+Builder::XmlMarkup is a library that allows easy programmatic creation
+of XML markup.  For example:
+
+  builder = Builder::XmlMarkup.new(:target=>STDOUT, :indent=>2)
+  builder.person { |b| b.name("Jim"); b.phone("555-1234") }
+
+will generate:
+
+  <person>
+    <name>Jim</name>
+    <phone>555-1234</phone>
+  </person>
+
+== Availability
+
+The easiest way to get and install builder is via RubyGems ...
+
+  gem install builder    (you may need root/admin privileges)
+
+== Thanks
+
+* Sam Ruby for the XChar module and the related UTF-8 translation
+  tools.
+* Also to Sam Ruby for gently persuading me to start quoting attribute
+  values.
+
+-- Jim Weirich

data/doc/releases/builder-2.1.1.rdoc

@@ -0,0 +1,58 @@
+= Builder 2.1.1 Released.
+
+Release 2.1.1 of Builder is mainly a bug fix release.
+
+== Changes in 2.1.1
+
+* Added <tt>reveal</tt> capability to BlankSlate.
+
+* Fixed a bug in BlankSlate where including a module into Object could
+  cause methods to leak into BlankSlate.
+
+* Fixed typo in XmlMarkup class docs (from Martin Fowler).
+
+* Fixed test on private methods to differentiate between targetted and
+  untargetted private methods.
+
+* Removed legacy capture of @self in XmlBase (@self was used back when
+  we used instance eval).
+
+* Added additional tests for global functions (both direct and
+  included).
+
+* Several misc internal cleanups, including rearranging the source
+  code tree.
+
+<b>NOTE:</b> The escaping attribute values by default is different
+than in previous releases of Builder.  This makes version 2.0.x
+somewhat incompatible with the 1.x series of Builder.  If you use "&",
+"<", or ">" in attributes values, you may have to change your
+code. (Essentially you remove the manual escaping.  The new way is
+easier, believe me).
+
+== What is Builder?
+
+Builder::XmlMarkup is a library that allows easy programmatic creation
+of XML markup.  For example:
+
+  builder = Builder::XmlMarkup.new(:target=>STDOUT, :indent=>2)
+  builder.person { |b| b.name("Jim"); b.phone("555-1234") }
+
+will generate:
+
+  <person>
+    <name>Jim</name>
+    <phone>555-1234</phone>
+  </person>
+
+== Availability
+
+The easiest way to get and install builder is via RubyGems ...
+
+  gem install builder    (you may need root/admin privileges)
+
+== Thanks
+
+* Martin Fowler for spotting some typos in the documentation.
+
+-- Jim Weirich

data/lib/blankslate.rb

@@ -0,0 +1,142 @@
+#!/usr/bin/env ruby
+#--
+# Copyright 2004, 2006 by Jim Weirich (jim@weirichhouse.org).
+# All rights reserved.
+
+# Permission is granted for use, copying, modification, distribution,
+# and distribution of modified versions of this work as long as the
+# above copyright notice is included.
+#++
+
+class String
+  if instance_methods.first.is_a?(Symbol)
+    def _blankslate_as_name
+      to_sym
+    end
+  else
+    def _blankslate_as_name
+      self
+    end
+  end
+end
+
+class Symbol
+  if instance_methods.first.is_a?(Symbol)
+    def _blankslate_as_name
+      self
+    end
+  else
+    def _blankslate_as_name
+      to_s
+    end
+  end
+end
+
+######################################################################
+# BlankSlate provides an abstract base class with no predefined
+# methods (except for <tt>\_\_send__</tt> and <tt>\_\_id__</tt>).
+# BlankSlate is useful as a base class when writing classes that
+# depend upon <tt>method_missing</tt> (e.g. dynamic proxies).
+#
+class BlankSlate
+  class << self
+
+    # Hide the method named +name+ in the BlankSlate class.  Don't
+    # hide +instance_eval+ or any method beginning with "__".
+    def hide(name)
+      warn_level = $VERBOSE
+      $VERBOSE = nil
+      if instance_methods.include?(name._blankslate_as_name) &&
+          name !~ /^(__|instance_eval$)/
+        @hidden_methods ||= {}
+        @hidden_methods[name.to_sym] = instance_method(name)
+        undef_method name
+      end
+    ensure
+      $VERBOSE = warn_level
+    end
+
+    def find_hidden_method(name)
+      @hidden_methods ||= {}
+      @hidden_methods[name] || superclass.find_hidden_method(name)
+    end
+
+    # Redefine a previously hidden method so that it may be called on a blank
+    # slate object.
+    def reveal(name)
+      hidden_method = find_hidden_method(name)
+      fail "Don't know how to reveal method '#{name}'" unless hidden_method
+      define_method(name, hidden_method)
+    end
+  end
+
+  instance_methods.each { |m| hide(m) }
+end
+
+######################################################################
+# Since Ruby is very dynamic, methods added to the ancestors of
+# BlankSlate <em>after BlankSlate is defined</em> will show up in the
+# list of available BlankSlate methods.  We handle this by defining a
+# hook in the Object and Kernel classes that will hide any method
+# defined after BlankSlate has been loaded.
+#
+module Kernel
+  class << self
+    alias_method :blank_slate_method_added, :method_added
+
+    # Detect method additions to Kernel and remove them in the
+    # BlankSlate class.
+    def method_added(name)
+      result = blank_slate_method_added(name)
+      return result if self != Kernel
+      BlankSlate.hide(name)
+      result
+    end
+  end
+end
+
+######################################################################
+# Same as above, except in Object.
+#
+class Object
+  class << self
+    alias_method :blank_slate_method_added, :method_added
+
+    # Detect method additions to Object and remove them in the
+    # BlankSlate class.
+    def method_added(name)
+      result = blank_slate_method_added(name)
+      return result if self != Object
+      BlankSlate.hide(name)
+      result
+    end
+
+    def find_hidden_method(name)
+      nil
+    end
+  end
+end
+
+######################################################################
+# Also, modules included into Object need to be scanned and have their
+# instance methods removed from blank slate.  In theory, modules
+# included into Kernel would have to be removed as well, but a
+# "feature" of Ruby prevents late includes into modules from being
+# exposed in the first place.
+#
+# NOTE (keeper): that Ruby "feature" is gone on modern Rubies -- a
+# module included into Kernel late IS visible through BlankSlate's
+# ancestry now, so Kernel includes are scanned too.  (Fixes
+# test_late_included_module_in_kernel_is_ok on Ruby >= 1.9.)
+#
+class Module
+  alias blankslate_original_append_features append_features
+  def append_features(mod)
+    result = blankslate_original_append_features(mod)
+    return result if mod != Object && mod != Kernel
+    instance_methods.each do |name|
+      BlankSlate.hide(name)
+    end
+    result
+  end
+end

data/lib/builder/blankslate.rb

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+#--
+# Copyright 2004, 2006 by Jim Weirich (jim@weirichhouse.org).
+# All rights reserved.
+
+# Permission is granted for use, copying, modification, distribution,
+# and distribution of modified versions of this work as long as the
+# above copyright notice is included.
+#++
+
+######################################################################
+# BlankSlate has been promoted to a top level name and is now
+# available as a standalone gem.  We make the name available in the
+# Builder namespace for compatibility.
+#
+module Builder
+  if Object::const_defined?(:BasicObject)
+    BlankSlate = ::BasicObject
+  else
+    require 'blankslate'
+    BlankSlate = ::BlankSlate
+  end
+end

data/lib/builder/version.rb

@@ -0,0 +1,8 @@
+module Builder
+  VERSION_NUMBERS = [
+    VERSION_MAJOR = 1,
+    VERSION_MINOR = 0,
+    VERSION_BUILD = 0,
+  ]
+  VERSION = VERSION_NUMBERS.join(".")
+end

data/lib/builder/xchar.rb

@@ -0,0 +1,197 @@
+#!/usr/bin/env ruby
+
+# The XChar library is provided courtesy of Sam Ruby (See
+# http://intertwingly.net/stories/2005/09/28/xchar.rb)
+
+# --------------------------------------------------------------------
+
+# If the Builder::XChar module is not currently defined, fail on any
+# name clashes in standard library classes.
+
+module Builder
+  def self.check_for_name_collision(klass, method_name, defined_constant=nil)
+    if klass.method_defined?(method_name.to_s)
+      fail RuntimeError,
+	"Name Collision: Method '#{method_name}' is already defined in #{klass}"
+    end
+  end
+end
+
+if ! defined?(Builder::XChar) and ! String.method_defined?(:encode)
+  Builder.check_for_name_collision(String, "to_xs")
+  Builder.check_for_name_collision(Fixnum, "xchr")
+end
+
+######################################################################
+module Builder
+
+  ####################################################################
+  # XML Character converter, from Sam Ruby:
+  # (see http://intertwingly.net/stories/2005/09/28/xchar.rb). 
+  #
+  module XChar # :nodoc:
+
+    # See
+    # http://intertwingly.net/stories/2004/04/14/i18n.html#CleaningWindows
+    # for details.
+    CP1252 = {			# :nodoc:
+      128 => 8364,		# euro sign
+      130 => 8218,		# single low-9 quotation mark
+      131 =>  402,		# latin small letter f with hook
+      132 => 8222,		# double low-9 quotation mark
+      133 => 8230,		# horizontal ellipsis
+      134 => 8224,		# dagger
+      135 => 8225,		# double dagger
+      136 =>  710,		# modifier letter circumflex accent
+      137 => 8240,		# per mille sign
+      138 =>  352,		# latin capital letter s with caron
+      139 => 8249,		# single left-pointing angle quotation mark
+      140 =>  338,		# latin capital ligature oe
+      142 =>  381,		# latin capital letter z with caron
+      145 => 8216,		# left single quotation mark
+      146 => 8217,		# right single quotation mark
+      147 => 8220,		# left double quotation mark
+      148 => 8221,		# right double quotation mark
+      149 => 8226,		# bullet
+      150 => 8211,		# en dash
+      151 => 8212,		# em dash
+      152 =>  732,		# small tilde
+      153 => 8482,		# trade mark sign
+      154 =>  353,		# latin small letter s with caron
+      155 => 8250,		# single right-pointing angle quotation mark
+      156 =>  339,		# latin small ligature oe
+      158 =>  382,		# latin small letter z with caron
+      159 =>  376,		# latin capital letter y with diaeresis
+    }
+
+    # See http://www.w3.org/TR/REC-xml/#dt-chardata for details.
+    PREDEFINED = {
+      38 => '&',		# ampersand
+      60 => '<',		# left angle bracket
+      62 => '>',		# right angle bracket
+    }
+
+    # See http://www.w3.org/TR/REC-xml/#charsets for details.
+    VALID = [
+      0x9, 0xA, 0xD,
+      (0x20..0xD7FF), 
+      (0xE000..0xFFFD),
+      (0x10000..0x10FFFF)
+    ]
+
+    # http://www.fileformat.info/info/unicode/char/fffd/index.htm
+    REPLACEMENT_CHAR =
+      if String.method_defined?(:encode)
+        "\uFFFD"
+      elsif $KCODE == 'UTF8'
+        "\xEF\xBF\xBD"
+      else
+        '*'
+      end
+  end
+
+end
+
+
+if String.method_defined?(:encode)
+  module Builder
+    module XChar # :nodoc:
+      CP1252_DIFFERENCES, UNICODE_EQUIVALENT = Builder::XChar::CP1252.each.
+        inject([[],[]]) {|(domain,range),(key,value)|
+          [domain << key,range << value]
+        }.map {|seq| seq.pack('U*').force_encoding('utf-8')}
+  
+      XML_PREDEFINED = Regexp.new('[' +
+        Builder::XChar::PREDEFINED.keys.pack('U*').force_encoding('utf-8') +
+      ']')
+  
+      INVALID_XML_CHAR = Regexp.new('[^'+
+        Builder::XChar::VALID.map { |item|
+          case item
+          when Integer
+            [item].pack('U').force_encoding('utf-8')
+          when Range
+            [item.first, '-'.ord, item.last].pack('UUU').force_encoding('utf-8')
+          end
+        }.join +
+      ']')
+  
+      ENCODING_BINARY = Encoding.find('BINARY')
+      ENCODING_UTF8   = Encoding.find('UTF-8')
+      ENCODING_ISO1   = Encoding.find('ISO-8859-1')
+
+      # convert a string to valid UTF-8, compensating for a number of
+      # common errors.
+      def XChar.unicode(string)
+        if string.encoding == ENCODING_BINARY
+          if string.ascii_only?
+            string
+          else
+            string = string.clone.force_encoding(ENCODING_UTF8)
+            if string.valid_encoding?
+              string
+            else
+              string.encode(ENCODING_UTF8, ENCODING_ISO1)
+            end
+          end
+
+        elsif string.encoding == ENCODING_UTF8
+          if string.valid_encoding?
+            string
+          else
+            string.encode(ENCODING_UTF8, ENCODING_ISO1)
+          end
+
+        else
+          string.encode(ENCODING_UTF8)
+        end
+      end
+
+      # encode a string per XML rules
+      def XChar.encode(string)
+        unicode(string).
+          tr(CP1252_DIFFERENCES, UNICODE_EQUIVALENT).
+          gsub(INVALID_XML_CHAR, REPLACEMENT_CHAR).
+          gsub(XML_PREDEFINED) {|c| PREDEFINED[c.ord]}
+      end
+    end
+  end
+
+else
+
+  ######################################################################
+  # Enhance the Fixnum class with a XML escaped character conversion.
+  #
+  class Fixnum
+    XChar = Builder::XChar if ! defined?(XChar)
+  
+    # XML escaped version of chr. When <tt>escape</tt> is set to false
+    # the CP1252 fix is still applied but utf-8 characters are not
+    # converted to character entities.
+    def xchr(escape=true)
+      n = XChar::CP1252[self] || self
+      case n when *XChar::VALID
+        XChar::PREDEFINED[n] or 
+          (n<128 ? n.chr : (escape ? "&##{n};" : [n].pack('U*')))
+      else
+        Builder::XChar::REPLACEMENT_CHAR
+      end
+    end
+  end
+  
+
+  ######################################################################
+  # Enhance the String class with a XML escaped character version of
+  # to_s.
+  #
+  class String
+    # XML escaped version of to_s. When <tt>escape</tt> is set to false
+    # the CP1252 fix is still applied but utf-8 characters are not
+    # converted to character entities.
+    def to_xs(escape=true)
+      unpack('U*').map {|n| n.xchr(escape)}.join # ASCII, UTF-8
+    rescue
+      unpack('C*').map {|n| n.xchr}.join # ISO-8859-1, WIN-1252
+    end
+  end
+end

data/lib/builder/xmlbase.rb

@@ -0,0 +1,199 @@
+#!/usr/bin/env ruby
+
+require 'builder/blankslate'
+
+module Builder
+
+  # Generic error for builder
+  class IllegalBlockError < RuntimeError; end
+
+  # XmlBase is a base class for building XML builders.  See
+  # Builder::XmlMarkup and Builder::XmlEvents for examples.
+  class XmlBase < BlankSlate
+
+    class << self
+      attr_accessor :cache_method_calls
+    end
+
+    # Create an XML markup builder.
+    #
+    # out      :: Object receiving the markup.  +out+ must respond to
+    #             <tt><<</tt>.
+    # indent   :: Number of spaces used for indentation (0 implies no
+    #             indentation and no line breaks).
+    # initial  :: Level of initial indentation.
+    # encoding :: When <tt>encoding</tt> and $KCODE are set to 'utf-8'
+    #             characters aren't converted to character entities in
+    #             the output stream.
+    def initialize(indent=0, initial=0, encoding='utf-8')
+      @indent = indent
+      @level  = initial
+      @encoding = encoding.downcase
+    end
+
+    def explicit_nil_handling?
+      @explicit_nil_handling
+    end
+
+    # Create a tag named +sym+.  Other than the first argument which
+    # is the tag name, the arguments are the same as the tags
+    # implemented via <tt>method_missing</tt>.
+    def tag!(sym, *args, &block)
+      text = nil
+      attrs = nil
+      sym = "#{sym}:#{args.shift}" if args.first.kind_of?(::Symbol)
+      sym = sym.to_sym unless sym.class == ::Symbol
+      args.each do |arg|
+        case arg
+        when ::Hash
+          attrs ||= {}
+          attrs.merge!(arg)
+        when nil
+          attrs ||= {}
+          attrs.merge!({:nil => true}) if explicit_nil_handling?
+        else
+          text ||= ''
+          text << arg.to_s
+        end
+      end
+      if block
+        unless text.nil?
+          ::Kernel::raise ::ArgumentError,
+            "XmlMarkup cannot mix a text argument with a block"
+        end
+        _indent
+        _start_tag(sym, attrs)
+        _newline
+        begin
+          _nested_structures(block)
+        ensure
+          _indent
+          _end_tag(sym)
+          _newline
+        end
+      elsif text.nil?
+        _indent
+        _start_tag(sym, attrs, true)
+        _newline
+      else
+        _indent
+        _start_tag(sym, attrs)
+        text! text
+        _end_tag(sym)
+        _newline
+      end
+      @target
+    end
+
+    # Create XML markup based on the name of the method.  This method
+    # is never invoked directly, but is called for each markup method
+    # in the markup block that isn't cached.
+    def method_missing(sym, *args, &block)
+      cache_method_call(sym) if ::Builder::XmlBase.cache_method_calls
+      tag!(sym, *args, &block)
+    end
+
+    # Append text to the output target.  Escape any markup.  May be
+    # used within the markup brackets as:
+    #
+    #   builder.p { |b| b.br; b.text! "HI" }   #=>  <p><br/>HI</p>
+    def text!(text)
+      _text(_escape(text))
+    end
+
+    # Append text to the output target without escaping any markup.
+    # May be used within the markup brackets as:
+    #
+    #   builder.p { |x| x << "<br/>HI" }   #=>  <p><br/>HI</p>
+    #
+    # This is useful when using non-builder enabled software that
+    # generates strings.  Just insert the string directly into the
+    # builder without changing the inserted markup.
+    #
+    # It is also useful for stacking builder objects.  Builders only
+    # use <tt><<</tt> to append to the target, so by supporting this
+    # method/operation builders can use other builders as their
+    # targets.
+    def <<(text)
+      _text(text)
+    end
+
+    # For some reason, nil? is sent to the XmlMarkup object.  If nil?
+    # is not defined and method_missing is invoked, some strange kind
+    # of recursion happens.  Since nil? won't ever be an XML tag, it
+    # is pretty safe to define it here. (Note: this is an example of
+    # cargo cult programming,
+    # cf. http://fishbowl.pastiche.org/2004/10/13/cargo_cult_programming).
+    def nil?
+      false
+    end
+
+    private
+
+    require 'builder/xchar'
+    if ::String.method_defined?(:encode)
+      def _escape(text)
+        result = XChar.encode(text)
+        begin
+          encoding = ::Encoding::find(@encoding)
+          raise Exception if encoding.dummy?
+          result.encode(encoding)
+        rescue
+          # if the encoding can't be supported, use numeric character references
+          result.
+            gsub(/[^\u0000-\u007F]/) {|c| "&##{c.ord};"}.
+            force_encoding('ascii')
+        end
+      end
+    else
+      def _escape(text)
+        if (text.method(:to_xs).arity == 0)
+          text.to_xs
+        else
+          text.to_xs((@encoding != 'utf-8' or $KCODE != 'UTF8'))
+        end
+      end
+    end
+
+    def _escape_attribute(text)
+      _escape(text).gsub("\n", "&#10;").gsub("\r", "&#13;").
+        gsub(%r{"}, '&quot;') # " WART
+    end
+
+    def _newline
+      return if @indent == 0
+      text! "\n"
+    end
+
+    def _indent
+      return if @indent == 0 || @level == 0
+      text!(" " * (@level * @indent))
+    end
+
+    def _nested_structures(block)
+      @level += 1
+      block.call(self)
+    ensure
+      @level -= 1
+    end
+
+    # If XmlBase.cache_method_calls = true, we dynamicly create the method
+    # missed as an instance method on the XMLBase object. Because XML
+    # documents are usually very repetative in nature, the next node will
+    # be handled by the new method instead of method_missing. As
+    # method_missing is very slow, this speeds up document generation
+    # significantly.
+    def cache_method_call(sym)
+      class << self; self; end.class_eval do
+        unless method_defined?(sym)
+          define_method(sym) do |*args, &block|
+            tag!(sym, *args, &block)
+          end
+        end
+      end
+    end
+  end
+
+  XmlBase.cache_method_calls = true
+
+end