xml-mapping 0.8

data/Rakefile

@@ -0,0 +1,214 @@
+# -*- ruby -*-
+# adapted from active_record's Rakefile
+
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+#require 'rake/contrib/rubyforgepublisher'
+require 'rake/contrib/sshpublisher'
+
+require File.dirname(__FILE__)+"/lib/xml/mapping/version"
+
+
+# yeah -- it's just stupid that these are private
+
+class Rake::RDocTask
+  public :rdoc_target
+end
+
+class Rake::PackageTask
+  public :tgz_file, :zip_file
+end
+
+class Rake::GemPackageTask
+  public :gem_file
+end
+
+
+FILES_RDOC_EXTRA=%w{README README_XPATH TODO.txt doc/xpath_impl_notes.txt}
+FILES_RDOC_INCLUDES=%w{examples/company.xml
+                       examples/company.rb
+                       examples/company_usage.intout
+                       examples/order_usage.intout
+                       examples/time_augm.intout
+                       examples/xpath_usage.intout
+                       examples/xpath_ensure_created.intout
+                       examples/xpath_create_new.intout
+                       examples/xpath_pathological.intout
+                       examples/xpath_docvsroot.intout
+                       examples/order_signature_enhanced_usage.intout}
+
+
+desc "Default Task"
+task :default => [ :test ]
+
+Rake::TestTask.new(:test) { |t|
+  t.test_files = ["test/all_tests.rb"]
+  t.verbose = true
+}
+
+# runs tests only if sources have changed since last succesful run of
+# tests
+file "test_run" => FileList.new('lib/**/*.rb','test/**/*.rb') do
+  Task[:test].invoke
+  touch "test_run"
+end
+
+
+
+Rake::RDocTask.new { |rdoc|
+  rdoc.rdoc_dir = 'doc/api'
+  rdoc.title    = "XML::Mapping -- Simple, extensible Ruby-to-XML (and back) mapper"
+  rdoc.options << '--line-numbers --inline-source --accessor cattr_accessor=object --include examples'
+  rdoc.rdoc_files.include(*FILES_RDOC_EXTRA)
+  rdoc.rdoc_files.include('lib/**/*.rb')
+
+  # additional file dependencies for the rdoc task
+  #   this somewhat of a black art because RDocTask doesn't document the
+  #   prerequisite of its rdoc task (<rdoc_dir>/index.html)
+  file rdoc.rdoc_target => FILES_RDOC_INCLUDES
+  file "#{rdoc.rdoc_dir}/index.html" => FileList.new("examples/**/*.rb")
+}
+
+#rule '.intout' => ['.intin.rb', *FileList.new("lib/**/*.rb")] do |task|  # doesn't work -- see below
+rule '.intout' => ['.intin.rb'] do |task|
+  this_file_re = Regexp.compile(Regexp.quote(__FILE__))
+  b = binding
+  visible=true; visible_retval=true; handle_exceptions=false
+  old_stdout = $stdout
+  old_wd = Dir.pwd
+  begin
+    File.open(task.name,"w") do |fout|
+      $stdout = fout
+      File.open(task.source,"r") do |fin|
+        Dir.chdir File.dirname(task.name)
+        fin.read.split("#<=\n").each do |snippet|
+
+          snippet.scan(/^#:(.*?):$/) do |(switch,)|
+            case switch
+            when "visible"
+              visible=true
+            when "invisible"
+              visible=false
+            when "visible_retval"
+              visible_retval=true
+            when "invisible_retval"
+              visible_retval=false
+            when "handle_exceptions"
+              handle_exceptions=true
+            when "no_exceptions"
+              handle_exceptions=false
+            end
+          end
+          snippet.gsub!(/^#:.*?:(?:\n|\z)/,'')
+
+          print "#{snippet}\n" if visible
+          exc_handled = false
+          value = begin
+                    eval(snippet,b)
+                  rescue Exception
+                    raise unless handle_exceptions
+                    exc_handled = true
+                    if visible
+                      print "#{$!.class}: #{$!}\n"
+                      for m in $@
+                        break if m=~this_file_re
+                        print "\tfrom #{m}\n"
+                      end
+                    end
+                  end
+          if visible and visible_retval and not exc_handled
+            print "=> #{value.inspect}\n"
+          end
+        end
+      end
+    end
+  rescue Exception
+    $stdout = old_stdout
+    Dir.chdir old_wd
+    File.delete task.name
+    raise
+  ensure
+    $stdout = old_stdout
+    Dir.chdir old_wd
+  end
+end
+
+# have to add additional prerequisites manually because it appears
+# that rules can only define a single prerequisite :-\
+for f in %w{examples/company_usage
+            examples/order_usage
+            examples/order_signature_enhanced_usage
+            examples/time_augm
+            examples/xpath_usage
+            examples/xpath_ensure_created
+            examples/xpath_create_new
+            examples/xpath_pathological
+            examples/xpath_docvsroot} do
+  file "#{f}.intout" => ["#{f}.intin.rb", 'examples/company.xml']
+  file "#{f}.intout" => FileList.new("lib/**/*.rb")
+  file "#{f}.intout" => FileList.new("examples/**/*.rb")
+end
+
+
+spec = Gem::Specification.new do |s|
+  s.name = 'xml-mapping'
+  s.version = XML::Mapping::VERSION
+  s.platform = Gem::Platform::RUBY
+  s.summary =
+    "An easy to use, extensible library for mapping Ruby objects to XML and back. Includes an XPath interpreter."
+
+  # Rubygems' RDoc support is incomplete... Can't seem to find a way
+  # to set the start page, or a set of files that should be includable
+  # but not processed by rdoc directly
+  s.files += FILES_RDOC_EXTRA
+  s.files += Dir.glob("{lib,examples,test}/**/*").delete_if do |item|
+    item.include?("CVS") || item =~ /~$/
+  end
+  s.files += %w{LICENSE Rakefile install.rb}
+  s.extra_rdoc_files = FILES_RDOC_EXTRA
+  s.rdoc_options += %w{--include examples}
+
+  s.require_path = 'lib'
+  s.autorequire = 'xml/mapping'
+
+  # s.add_dependency 'rexml'
+
+  s.has_rdoc=true
+
+  s.test_file = 'test/all_tests.rb'
+
+  s.author = 'Olaf Klischat'
+  s.email = 'klischat@cs.tu-berlin.de'
+  s.homepage = "http://xml-mapping.rubyforge.org"
+end
+
+
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+
+  # (indirectly) add :rdoc, :test as prerequisites to :package task
+  # created by GemPackageTask
+  file "#{p.package_dir}/#{p.tgz_file}"  => [ "test_run", :rdoc ]
+  file "#{p.package_dir}/#{p.zip_file}" => [ "test_run", :rdoc ]
+  file "#{p.package_dir}/#{p.gem_file}" => [ "test_run", :rdoc ]
+end
+
+
+
+# run "rake package" to generate tgz, zip, gem in pkg/
+
+
+
+task :rfpub_rdoc => [:rdoc] do
+  p=Rake::SshDirPublisher.new('xml-mapping.rubyforge.org',
+                              '/var/www/gforge-projects/xml-mapping/',
+                              'doc/api')
+  p.upload
+end

data/TODO.txt

@@ -0,0 +1,32 @@
+- XML::XXPath: generalize foo[@x='bar'] to foo[<any XPath
+  expression>='bar'] (unless create/create_new implementation proves
+  to be too difficult, but I don't think it will...)
+
+- documentation:
+
+  - README:
+
+    - multi-attribute nodes
+
+- XML::Mapping: Move @options hash functionality from
+  SingleAttributeNode to Node.
+
+- XML::Mapping/default attribute values: Update documentation, digest
+  "nil" issues...
+
+- add streaming input/output to XML::Mapping, i.e. SAX-based input in
+  addition to the current REXML/DOM - based one. Probably won't be
+  implementable for some more complicated XPaths -- raise meaningful
+  exceptions in those cases.
+
+- XML::XXPath/XML::Mapping: add XML text nodes (the sub-node of an
+  element node that contains that element's text) first-class to
+  XML::XXPath. Use it for things like text_node :contents, "text()".
+
+  Along those lines: promote XPath node "unspecifiedness" from an
+  attribute to a REXML node object of "unspecified" class that's
+  turned into an attribute/element/text node when necessary
+
+- (eventually, maybe) provide a "scaffolding" feature to automatically
+  turn a dtd/schema into a set of node type definitions or even a set
+  of mapping classes

data/doc/xpath_impl_notes.txt

@@ -0,0 +1,119 @@
+=== latest design (12/2004)
+
+At the lowest level, the "Accessors" sub-module contains reader and
+creator functions that correspond to the various types of path
+elements (_elt_name_, @_attr_name_,
+_elt_name_[@_attr_name_='_attr_value_'] etc.) that xml-xxpath
+supports. A reader function gets an array of nodes and the search
+parameters corresponding to its path element type (e.g. _elt_name_,
+_attr_name_, _attr_value_) and returns an array with all matching
+direct sub-nodes of any of the supplied nodes. A creator function gets
+one node and the search parameters and returns the created sub-node.
+
+An XPath expression <tt><things1>/<things2>/.../<thingsx></tt> is
+compiled into a bunch of nested closures, each of which is responsible
+for a specific path element and calls the corresponding accessor
+function:
+
+- <tt>@creator_procs</tt> -- an array of "creator"
+  functions. <tt>@creator_procs[i]</tt> gets passed a base node (XML
+  element) and a create_new flag, and it creates the path
+  <tt><things[x-i+1]>/<things[x-i+2]>/.../<thingsx></tt> inside the
+  base node and returns the hindmost element created (i.e. the one
+  corresponding to <tt><thingsx></tt>).
+
+- <tt>@reader_proc</tt> -- a "reader" function that gets passed an
+  array of nodes and returns an array of all nodes that matched the
+  path in any of the supplied nodes, or, if no match was found, throws
+  :not_found along with the last non-empty set of nodes that was
+  found, and the element of <tt>@creator_procs</tt> that could be used
+  to create the remaining part of the path.
+
+The +all+ function is then trivially implemented on top of this:
+
+    def all(node,options={})
+      raise "options not a hash" unless Hash===options
+      if options[:create_new]
+        return [ @creator_procs[-1].call(node,true) ]
+      else
+        last_nodes,rest_creator = catch(:not_found) do
+          return @reader_proc.call([node])
+        end
+        if options[:ensure_created]
+          [ rest_creator.call(last_nodes[0],false) ]
+        else
+          []
+        end
+      end
+    end
+
+...and +first+, <tt>create_new</tt> etc. are even more trivial
+frontends to that.
+
+The implementations of the <tt>@creator_procs</tt> look like this:
+
+  @creator_procs[0] =
+    proc{|node,create_new| node}
+
+  @creator_procs[1] =
+    proc {|node,create_new|
+      @creator_procs[0].call(Accessors.create_subnode_by_<thingsx>(node,create_new,<thingsx>),
+                             create_new)
+    }
+
+  @creator_procs[2] =
+    proc {|node,create_new|
+      @creator_procs[1].call(Accessors.create_subnode_by_<thingsx-1>(node,create_new,<thingsx-1>),
+                             create_new)
+    }
+
+  ...
+
+  @creator_procs[n] =
+    proc {|node,create_new|
+      @creator_procs[n-1].call(Accessors.create_subnode_by_<things[x+1-n]>(node,create_new,<things[x+1-n]>),
+                               create_new)
+    }
+
+  ...
+  @creator_procs[x] =
+    proc {|node,create_new|
+      @creator_procs[x-1].call(Accessors.create_subnode_by_<things1>(node,create_new,<things1>),
+                               create_new)
+    }
+
+
+
+..and the implementation of @reader_proc looks like this:
+
+  @reader_proc = rpx where
+
+  rp0 = proc {|nodes| nodes}
+
+  rp1 = proc {|nodes|
+                next_nodes = Accessors.subnodes_by_<thingsx>(nodes,<thingsx>)
+                if (next_nodes == [])
+                  throw :not_found, [nodes,@creator_procs[1]]
+                else
+                  rp0.call(next_nodes)
+                end
+              }
+
+  rp2 = proc {|nodes|
+                next_nodes = Accessors.subnodes_by_<thingsx-1>(nodes,<thingsx-1>)
+                if (next_nodes == [])
+                  throw :not_found, [nodes,@creator_procs[2]]
+                else
+                  rp1.call(next_nodes)
+                end
+              }
+  ...
+
+  rpx = proc {|nodes|
+                next_nodes = Accessors.subnodes_by_<things1>(nodes,<things1>)
+                if (next_nodes == [])
+                  throw :not_found, [nodes,@creator_procs[x]]
+                else
+                  rpx-1.call(next_nodes)
+                end
+              }

data/examples/company.rb

@@ -0,0 +1,34 @@
+require 'xml/mapping'
+
+## forward declarations
+class Address; end
+class Customer; end
+
+
+class Company
+  include XML::Mapping
+
+  text_node :name, "@name"
+  object_node :address, "address", :class=>Address
+  array_node :customers, "customers", "customer", :class=>Customer
+end
+
+
+class Address
+  include XML::Mapping
+
+  text_node :city, "city"
+  numeric_node :zip, "zip"
+end
+
+
+class Customer
+  include XML::Mapping
+
+  text_node :id, "@id"
+  text_node :name, "name"
+
+  def initialize(id,name)
+    @id,@name = [id,name]
+  end
+end

data/examples/company.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<company name="ACME inc.">
+
+    <address>
+      <city>Berlin</city>
+      <zip>10113</zip>
+    </address>
+
+    <customers>
+
+      <customer id="jim">
+        <name>James Kirk</name>
+      </customer>
+
+      <customer id="ernie">
+        <name>Ernie</name>
+      </customer>
+
+      <customer id="bert">
+        <name>Bert</name>
+      </customer>
+
+    </customers>
+
+</company>

data/examples/company_usage.intin.rb

@@ -0,0 +1,19 @@
+#:invisible:
+$:.unshift "../lib"
+begin
+  Object.send(:remove_const, "Address")  # name clash with order_usage...
+rescue
+end
+require 'company' #<=
+#:visible:
+c = Company.load_from_file('company.xml') #<=
+c.name #<=
+c.customers.size #<=
+c.customers[1] #<=
+c.customers[1].name #<=
+c.customers[0].name #<=
+c.customers[0].name = 'James Tiberius Kirk' #<=
+c.customers << Customer.new('cm','Cookie Monster') #<=
+xml2 = c.save_to_xml #<=
+#:invisible_retval:
+xml2.write($stdout,2) #<=