bigfleet-builder 2.2.1

data/CHANGES

@@ -0,0 +1,89 @@
+= Change Log
+
+== Version 2.2.0
+
+* Applied patch from Thijs van der Vossen to allow UTF-8 encoded
+  output when the encoding is UTF-8 and $KCODE is UTF8.
+
+== Version 2.1.2
+
+* Fixed bug where private methods in kernel could leak through using
+  tag!().  Thanks to Hagen Overdick for finding and diagnosing this
+  bug.
+
+== Version 2.1.1
+
+* Fixed typo in XmlMarkup class docs (ident => indent). (from Martin
+  Fowler).
+* Removed extra directory indirection from legacy CVS to SVN move.
+* Removed some extraneous tabs from source.
+* Fixed test on private methods in blankslate 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).
+
+== Version 2.1.0
+
+* Fixed bug in BlankSlate where including a module into Object could
+  cause methods to leak into BlankSlate.
+* Made BlankSlate available as its own gem.  Currently the builder gem
+  still directly includes the BlankSlate code.
+* Added reveal capability to BlankSlate.
+
+== Version 2.0.0
+
+* Added doc directory
+* Added unit tests for XmlEvents.
+* Added XChar module and used it in the _escape method.
+* Attributes are now quoted by default when strings.  Use Symbol
+  attribute values for unquoted behavior.
+
+== Version 1.2.4
+
+* Added a cdata! command to an XML Builder (from Josh Knowles).
+
+== Version 1.2.3
+
+The attributes in the <?xml ... ?> instruction will be ordered:
+version, encoding, standalone.
+
+== Version 1.2.2
+
+Another fix for BlankSlate.  The Kernal/Object traps added in 1.2.1
+failed when a method was defined late more than once.  Since the
+method was already marked as removed, another attempt to undefine it
+raised an error.  The fix was to check the list of instance methods
+before attempting the undef operation.  Thanks to Florian Gross and
+David Heinemeier Hansson for the patch.
+
+== Version 1.2.1
+
+BlankSlate now traps method definitions in Kernel and Object to avoid
+late method definitions inadvertently becoming part of the definition
+of BlankSlate as well.
+
+== Version 1.2.0
+
+Improved support for entity declarations by allowing nested
+declarations and removal of the attribute processing.
+
+Added namespace support.
+
+== Version 1.1.0
+
+Added support for comments, entity declarations and processing instructions.
+
+== Version 1.0.0
+
+Removed use of <tt>instace_eval</tt> making the use of XmlMarkup much
+less prone to error.
+
+== Version 0.1.1
+
+Bug fix.
+
+== Version 0.1.0
+
+Initial version release.
+

data/README

@@ -0,0 +1,225 @@
+= Project: Builder
+
+== Goal
+
+Provide a simple way to create XML markup and data structures.
+
+== Classes
+
+Builder::XmlMarkup:: Generate XML markup notiation
+Builder::XmlEvents:: Generate XML events (i.e. SAX-like)
+
+<b>Notes</b>:: 
+
+* An <tt>Builder::XmlTree</tt> class to generate XML tree
+  (i.e. DOM-like) structures is also planned, but not yet implemented.
+  Also, the events builder is currently lagging the markup builder in
+  features.
+
+== Usage
+
+  require 'rubygems'	
+  require_gem 'builder', '~> 2.0'
+
+  builder = Builder::XmlMarkup.new
+  xml = builder.person { |b| b.name("Jim"); b.phone("555-1234") }
+  xml #=> <person><name>Jim</name><phone>555-1234</phone></person>
+
+or
+
+  require 'rubygems'	
+  require_gem 'builder'
+
+  builder = Builder::XmlMarkup.new(:target=>STDOUT, :indent=>2)
+  builder.person { |b| b.name("Jim"); b.phone("555-1234") }
+  #
+  # Prints:
+  # <person>
+  #   <name>Jim</name>
+  #   <phone>555-1234</phone>
+  # </person>
+
+== Compatibility
+
+=== Version 2.0.0 Compatibility Changes
+
+Version 2.0.0 introduces automatically escaped attribute values for
+the first time.  Versions prior to 2.0.0 did not insert escape
+characters into attribute values in the XML markup.  This allowed
+attribute values to explicitly reference entities, which was
+occasionally used by a small number of developers.  Since strings
+could always be explicitly escaped by hand, this was not a major
+restriction in functionality.
+
+However, it did suprise most users of builder.  Since the body text is
+normally escaped, everybody expected the attribute values to be
+escaped as well.  Escaped attribute values were the number one support
+request on the 1.x Builder series.
+
+Starting with Builder version 2.0.0, all attribute values expressed as
+strings will be processed and the appropriate characters will be
+escaped (e.g. "&" will be tranlated to "&amp;").  Attribute values
+that are expressed as Symbol values will not be processed for escaped
+characters and will be unchanged in output. (Yes, this probably counts
+as Symbol abuse, but the convention is convenient and flexible).
+
+Example:
+
+  xml = Builder::XmlMarkup.new
+  xml.sample(:escaped=>"This&That", :unescaped=>:"Here&amp;There")
+  xml.target!  =>
+    <sample escaped="This&amp;That" unescaped="Here&amp;There"/>
+
+=== Version 1.0.0 Compatibility Changes
+
+Version 1.0.0 introduces some changes that are not backwards
+compatible with earlier releases of builder.  The main areas of
+incompatibility are:
+
+* Keyword based arguments to +new+ (rather than positional based).  It
+  was found that a developer would often like to specify indentation
+  without providing an explicit target, or specify a target without
+  indentation.  Keyword based arguments handle this situation nicely.
+
+* Builder must now be an explicit target for markup tags.  Instead of
+  writing
+
+    xml_markup = Builder::XmlMarkup.new
+    xml_markup.div { strong("text") }
+
+  you need to write
+
+    xml_markup = Builder::XmlMarkup.new
+    xml_markup.div { xml_markup.strong("text") }
+
+* The builder object is passed as a parameter to all nested markup
+  blocks.  This allows you to create a short alias for the builder
+  object that can be used within the block.  For example, the previous
+  example can be written as:
+
+    xml_markup = Builder::XmlMarkup.new
+    xml_markup.div { |xml| xml.strong("text") }
+
+* If you have both a pre-1.0 and a post-1.0 gem of builder installed,
+  you can choose which version to use through the RubyGems
+  +require_gem+ facility.
+
+    require_gem 'builder', "~> 0.0"   # Gets the old version
+    require_gem 'builder', "~> 1.0"   # Gets the new version
+
+== Features
+
+* XML Comments are supported ...
+
+    xml_markup.comment! "This is a comment"
+      #=>  <!-- This is a comment -->
+
+* XML processing instructions are supported ...
+
+    xml_markup.instruct! :xml, :version=>"1.0", :encoding=>"UTF-8"
+      #=>  <?xml version="1.0" encoding="UTF-8"?>
+   
+  If the processing instruction is omitted, it defaults to "xml".
+  When the processing instruction is "xml", the defaults attributes
+  are:
+  
+  <b>version</b>:: 1.0
+  <b>encoding</b>:: "UTF-8"
+
+  (NOTE: if the encoding is set to "UTF-8" and $KCODE is set to
+  "UTF8", then Builder will emit UTF-8 encoded strings rather than
+  encoding non-ASCII characters as entities.)
+
+* XML entity declarations are now supported to a small degree.
+
+    xml_markup.declare! :DOCTYPE, :chapter, :SYSTEM, "../dtds/chapter.dtd"
+      #=>  <!DOCTYPE chapter SYSTEM "../dtds/chapter.dtd">
+
+  The parameters to a declare! method must be either symbols or
+  strings. Symbols are inserted without quotes, and strings are
+  inserted with double quotes.  Attribute-like arguments in hashes are
+  not allowed.
+
+  If you need to have an argument to declare! be inserted without
+  quotes, but the arguement does not conform to the typical Ruby
+  syntax for symbols, then use the :"string" form to specify a symbol.
+
+  For example:
+
+    xml_markup.declare! :ELEMENT, :chapter, :"(title,para+)"
+      #=>  <!ELEMENT chapter (title,para+)>
+
+  Nested entity declarations are allowed.  For example:
+
+    @xml_markup.declare! :DOCTYPE, :chapter do |x|
+      x.declare! :ELEMENT, :chapter, :"(title,para+)"
+      x.declare! :ELEMENT, :title, :"(#PCDATA)"
+      x.declare! :ELEMENT, :para, :"(#PCDATA)"
+    end
+
+    #=>
+
+    <!DOCTYPE chapter [
+      <!ELEMENT chapter (title,para+)>
+      <!ELEMENT title (#PCDATA)>
+      <!ELEMENT para (#PCDATA)>
+    ]>
+
+* Some support for XML namespaces is now available.  If the first
+  argument to a tag call is a symbol, it will be joined to the tag to
+  produce a namespace:tag combination.  It is easier to show this than
+  describe it.
+
+   xml.SOAP :Envelope do ... end
+
+  Just put a space before the colon in a namespace to produce the
+  right form for builder (e.g. "<tt>SOAP:Envelope</tt>" =>
+  "<tt>xml.SOAP :Envelope</tt>")
+
+* String attribute values are <em>now</em> escaped by default by
+  Builder (<b>NOTE:</b> this is _new_ behavior as of version 2.0).
+
+  However, occasionally you need to use entities in attribute values.
+  Using a symbols (rather than a string) for an attribute value will
+  cause Builder to not run its quoting/escaping algorithm on that
+  particular value.
+
+  (<b>Note:</b> The +escape_attrs+ option for builder is now
+  obsolete).
+
+  Example:
+
+    xml = Builder::XmlMarkup.new
+    xml.sample(:escaped=>"This&That", :unescaped=>:"Here&amp;There")
+    xml.target!  =>
+      <sample escaped="This&amp;That" unescaped="Here&amp;There"/>
+
+* UTF-8 Support
+
+  Builder correctly translates UTF-8 characters into valid XML.  (New
+  in version 2.0.0).  Thanks to Sam Ruby for the translation code.
+
+  Example:
+
+    xml = Builder::XmlMarkup.new
+    xml.sample("I�t�rn�ti�n�l")
+    xml.target!  =>
+      "<sample>I&#241;t&#235;rn&#226;ti&#244;n&#224;l</sample>"
+
+  You can get UTF-8 encoded output by making sure that the XML
+  encoding is set to "UTF-8" and that the $KCODE variable is set to
+  "UTF8".
+
+    $KCODE = 'UTF8'
+    xml = Builder::XmlMarkup.new
+    xml.instruct!(:xml, :encoding => "UTF-8")
+    xml.sample("I�t�rn�ti�n�l")
+    xml.target!  =>
+      "<sample>I�t�rn�ti�n�l</sample>"
+
+== Contact
+
+Author::     Jim Weirich
+Email::      jim@weirichhouse.org
+Home Page::  http://onestepback.org
+License::    MIT Licence (http://www.opensource.org/licenses/mit-license.html)

data/Rakefile

@@ -0,0 +1,297 @@
+# Rakefile for rake        -*- ruby -*-
+
+# Copyright 2004, 2005, 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.
+
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/rdoctask'
+begin
+  require 'rubygems'
+  require 'rake/gempackagetask'
+rescue Exception
+  nil
+end
+
+# Determine the current version of the software
+
+CLOBBER.include('pkg')
+
+CURRENT_VERSION = '2.2.0'
+PKG_VERSION = ENV['REL'] ? ENV['REL'] : CURRENT_VERSION
+
+SRC_RB = FileList['lib/**/*.rb']
+
+# The default task is run if rake is given no explicit arguments.
+
+desc "Default Task"
+task :default => :test_all
+
+# Test Tasks ---------------------------------------------------------
+
+desc "Run all tests"
+task :test_all => [:test_units]
+task :ta => [:test_all]
+
+task :tu => [:test_units]
+
+Rake::TestTask.new("test_units") do |t|
+  t.test_files = FileList['test/test*.rb']
+  t.verbose = false
+end
+
+# Create a task to build the RDOC documentation tree.
+
+rd = Rake::RDocTask.new("rdoc") { |rdoc|
+  rdoc.rdoc_dir = 'html'
+  rdoc.title    = "Builder for Markup"
+  rdoc.options << '--line-numbers' << '--inline-source' << '--main' << 'README'
+  rdoc.rdoc_files.include('lib/**/*.rb', '[A-Z]*', 'doc/**/*.rdoc')
+  rdoc.template = 'doc/jamis.rb'
+}
+
+# ====================================================================
+# Create a task that will package the Rake software into distributable
+# gem files.
+
+PKG_FILES = FileList[
+  'lib/**/*.rb', 
+  'test/**/*.rb',
+  'scripts/**/*.rb'
+]
+PKG_FILES.exclude('test/testcssbuilder.rb')
+PKG_FILES.exclude('lib/builder/css.rb')
+
+BLANKSLATE_FILES = FileList[
+  'lib/blankslate.rb',
+  'test/testblankslate.rb'
+]
+
+if ! defined?(Gem)
+  puts "Package Target requires RubyGEMs"
+else
+  spec = Gem::Specification.new do |s|
+    
+    #### Basic information.
+
+    s.name = 'builder'
+    s.version = PKG_VERSION
+    s.summary = "Builders for MarkUp."
+    s.description = %{\
+Builder provides a number of builder objects that make creating structured data
+simple to do.  Currently the following builder objects are supported:
+
+* XML Markup
+* XML Events
+}
+
+    s.files = PKG_FILES.to_a
+    s.require_path = 'lib'
+    s.autorequire = 'builder'
+    
+    s.test_files = PKG_FILES.select { |fn| fn =~ /^test\/test/ }
+    
+    s.has_rdoc = true
+    s.extra_rdoc_files = rd.rdoc_files.reject { |fn| fn =~ /\.rb$/ }.to_a
+    s.rdoc_options <<
+      '--title' <<  'Builder -- Easy XML Building' <<
+      '--main' << 'README' <<
+      '--line-numbers'
+    
+    s.author = "Jim Weirich"
+    s.email = "jim@weirichhouse.org"
+    s.homepage = "http://onestepback.org"
+  end
+  
+  blankslate_spec = Gem::Specification.new do |s|
+    
+    #### Basic information.
+    
+    s.name = 'blankslate'
+    s.version = PKG_VERSION
+    s.summary = "Blank Slate base class."
+    s.description = %{\
+BlankSlate provides a base class where almost all of the methods from Object and
+Kernel have been removed.  This is useful when providing proxy object and other
+classes that make heavy use of method_missing.  
+}
+    
+    s.files = BLANKSLATE_FILES.to_a
+    s.require_path = 'lib'
+    s.autorequire = 'builder'
+    
+    s.test_files = PKG_FILES.select { |fn| fn =~ /^test\/test/ }
+    
+    s.has_rdoc = true
+    s.extra_rdoc_files = rd.rdoc_files.reject { |fn| fn =~ /\.rb$/ }.to_a
+    s.rdoc_options <<
+      '--title' <<  'BlankSlate -- Base Class for building proxies.' <<
+      '--main' << 'README' <<
+      '--line-numbers'
+    
+    s.author = "Jim Weirich"
+    s.email = "jim@weirichhouse.org"
+    s.homepage = "http://onestepback.org"
+  end
+  
+  namespace 'builder' do
+    Rake::GemPackageTask.new(spec) do |t|
+      t.need_tar = true
+    end
+  end
+  
+  namespace 'blankslate' do
+    Rake::GemPackageTask.new(blankslate_spec) do |t|
+      t.need_tar = true
+    end
+  end
+
+  task :package => ['builder:package', 'blankslate:package']
+end
+
+desc "Look for Debugging print lines"
+task :dbg do
+  FileList['**/*.rb'].egrep /\bDBG|\bbreakpoint\b/
+end
+  
+
+# RCov ---------------------------------------------------------------
+begin
+  require 'rcov/rcovtask'
+
+  Rcov::RcovTask.new do |t|
+    t.libs << "test"
+    t.rcov_opts = [
+      '-xRakefile', '--text-report'
+    ]
+    t.test_files = FileList[
+      'test/test*.rb'
+    ]
+    t.output_dir = 'coverage'
+    t.verbose = true
+  end
+rescue LoadError
+  # No rcov available
+end
+
+# Tags file ----------------------------------------------------------
+
+namespace "tags" do
+  desc "Create a TAGS file"
+  task :emacs => "TAGS"
+  
+  TAGS = 'xctags -e'
+  
+  file "TAGS" => SRC_RB do
+    puts "Makings TAGS"
+    sh "#{TAGS} #{SRC_RB}", :verbose => false
+  end
+end
+  
+# --------------------------------------------------------------------
+# Creating a release
+
+def announce(msg='')
+  STDERR.puts msg
+end
+
+desc "Make a new release"
+task :release => [
+  :prerelease,
+  :clobber,
+  :test_all,
+  :update_version,
+  :package,
+  :tag] do
+  
+  announce 
+  announce "**************************************************************"
+  announce "* Release #{PKG_VERSION} Complete."
+  announce "* Packages ready to upload."
+  announce "**************************************************************"
+  announce 
+end
+
+# Validate that everything is ready to go for a release.
+task :prerelease do
+  announce 
+  announce "**************************************************************"
+  announce "* Making RubyGem Release #{PKG_VERSION}"
+  announce "* (current version #{CURRENT_VERSION})"
+  announce "**************************************************************"
+  announce  
+
+  # Is a release number supplied?
+  unless ENV['REL']
+    fail "Usage: rake release REL=x.y.z [REUSE=tag_suffix]"
+  end
+
+  # Is the release different than the current release.
+  # (or is REUSE set?)
+  if PKG_VERSION == CURRENT_VERSION && ! ENV['REUSE']
+    fail "Current version is #{PKG_VERSION}, must specify REUSE=tag_suffix to reuse version"
+  end
+
+  # Are all source files checked in?
+  if ENV['RELTEST']
+    announce "Release Task Testing, skipping checked-in file test"
+  else
+    announce "Checking for unchecked-in files..."
+    data = `cvs -q update`
+    unless data =~ /^$/
+      fail "CVS update is not clean ... do you have unchecked-in files?"
+    end
+    announce "No outstanding checkins found ... OK"
+  end
+end
+
+task :update_version => [:prerelease] do
+  if PKG_VERSION == CURRENT_VERSION
+    announce "No version change ... skipping version update"
+  else
+    announce "Updating Builder version to #{PKG_VERSION}"
+    open("Rakefile") do |rakein|
+      open("Rakefile.new", "w") do |rakeout|
+	rakein.each do |line|
+	  if line =~ /^CURRENT_VERSION\s*=\s*/
+	    rakeout.puts "CURRENT_VERSION = '#{PKG_VERSION}'"
+	  else
+	    rakeout.puts line
+	  end
+	end
+      end
+    end
+    mv "Rakefile.new", "Rakefile"
+    if ENV['RELTEST']
+      announce "Release Task Testing, skipping commiting of new version"
+    else
+      sh %{cvs commit -m "Updated to version #{PKG_VERSION}" Rakefile}
+    end
+  end
+end
+
+desc "Tag all the CVS files with the latest release number (REL=x.y.z)"
+task :tag => [:prerelease] do
+  reltag = "REL_#{PKG_VERSION.gsub(/\./, '_')}"
+  reltag << ENV['REUSE'].gsub(/\./, '_') if ENV['REUSE']
+  announce "Tagging CVS with [#{reltag}]"
+  if ENV['RELTEST']
+    announce "Release Task Testing, skipping CVS tagging"
+  else
+    sh %{cvs tag #{reltag}}
+  end
+end
+
+desc "Install the jamis RDoc template"
+task :install_jamis_template do
+  require 'rbconfig'
+  dest_dir = File.join(Config::CONFIG['rubylibdir'], "rdoc/generators/template/html")
+  fail "Unabled to write to #{dest_dir}" unless File.writable?(dest_dir)
+  install "doc/jamis.rb", dest_dir, :verbose => true
+end
+
+require 'scripts/publish'