xml-mapping 0.8.1 → 0.9.1

data/README_XPATH

@@ -8,12 +8,18 @@ uses xml-xxpath extensively for implementing its node types -- see the
 README file and the reference documentation (and the source code) for
 details. xml-xxpath, however, does not depend on xml-mapping at all,
 and is useful in its own right -- maybe I'll later distribute it as a
-seperate library instead of bundling it. xml-xxpath's XPath support is
-vastly incomplete (see below), but, in addition to the normal
-reading/matching functionality found in other XPath implementations
-(i.e. "find all elements in a given XML document matching a given
-XPath expression"), xml-xxpath supports <i>write access</i>. For
-example, when writing the XPath expression
+seperate library instead of bundling it. For the time being, if you
+want to use this XPath implementation stand-alone, you can just rip
+the files <tt>lib/xml/xxpath.rb</tt>,
+<tt>lib/xml/xxpath/steps.rb</tt>, and
+<tt>lib/xml/xxpath_methods.rb</tt> out of the xml-mapping distribution
+and use them on their own (they do not depend on anything else).
+
+xml-xxpath's XPath support is vastly incomplete (see below), but, in
+addition to the normal reading/matching functionality found in other
+XPath implementations (i.e. "find all elements in a given XML document
+matching a given XPath expression"), xml-xxpath supports <i>write
+access</i>. For example, when writing the XPath expression
 "/foo/bar[3]/baz[@key='hiho']" to the XML document
 
   <foo>
@@ -40,14 +46,13 @@ of the existing XPath implementations, e.g. the one that comes with
 REXML. Also, the whole xml-xxpath implementation is just 300 lines of
 Ruby code, it is quite fast (paths are precompiled), and xml-xxpath
 returns matched elements in the order they appeared in the source
-document -- I've heard REXML::XXPath doesn't do that :)
+document -- I've heard REXML::XPath doesn't do that :)
 
-Some basic knowledge of XPath is helpful for reading this document (I
-don't know very much either).
+Some basic knowledge of XPath is helpful for reading this document.
 
 At the moment, xml-xxpath understands XPath expressions of the form
-[<tt>/</tt>]_pathelement_<tt>/</tt>_pathelement_<tt>/</tt>..., where
-each _pathelement_ must be one of these:
+[<tt>/</tt>]_pathelement_<tt>/[/]</tt>_pathelement_<tt>/[/]</tt>...,
+where each _pathelement_ must be one of these:
 
 - a simple element name _name_, e.g. +signature+
 
@@ -60,6 +65,23 @@ each _pathelement_ must be one of these:
 
 - the "match-all" path element, <tt>*</tt>
 
+- .
+
+- name1|name2|...
+
+- .[@key='xy'] / self::*[@key='xy']
+
+- child::*[@key='xy']
+
+- text()
+
+
+
+Xml-xxpath only supports relative paths at this time, i.e. XPath
+expressions beginning with "/" or "//" will still only find nodes
+below the node the expression is applied to (as if you had written
+"./" or ".//", respectively).
+
 
 == Usage
 
@@ -115,7 +137,7 @@ against the +firstelt+ element in the example *must not* start with
 
 === Write Access
 
-You may pass a <tt>:ensure_created=>true</tt> option argument to
+You may pass an <tt>:ensure_created=>true</tt> option argument to
 _path_.first(_elt_)/_path_.all(_elt_) calls to make sure that _path_
 exists inside the passed XML element _elt_. If it existed before,
 nothing changes, and the call behaves just as it would without the
@@ -141,13 +163,18 @@ Examples:
 Alternatively, you may pass a <tt>:create_new=>true</tt> option
 argument or call <tt>create_new</tt> (_path_.create_new(_elt_) is
 equivalent to _path_.first(_elt_,:create_new=>true)). In that case, a
-new node in created in _elt_ for each path element of _path_ (or an
+new node is created in _elt_ for each path element of _path_ (or an
 exception raised if that wasn't possible for any path element).
 
 Examples:
 
   :include: xpath_create_new.intout
 
+This feature is used in xml-mapping by node types like
+XML::Mapping::ArrayNode, which must create a new instance of the
+"per-array element path" for each element of the array to be stored in
+an XML tree.
+
 
 === Pathological Cases
 

data/Rakefile

@@ -1,10 +1,12 @@
 # -*- ruby -*-
 # adapted from active_record's Rakefile
 
+require 'build_lib/rdoc_ext'
+
 require 'rubygems'
 require 'rake'
 require 'rake/testtask'
-require 'rake/rdoctask'
+require 'build_lib/my_rdoctask'
 require 'rake/packagetask'
 require 'rake/gempackagetask'
 #require 'rake/contrib/rubyforgepublisher'
@@ -12,13 +14,8 @@ 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
@@ -28,18 +25,33 @@ class Rake::GemPackageTask
 end
 
 
-FILES_RDOC_EXTRA=%w{README README_XPATH TODO.txt doc/xpath_impl_notes.txt}
+FILES_RDOC_EXTRA=%w{README README_XPATH ChangeLog TODO.txt doc/xpath_impl_notes.txt}
 FILES_RDOC_INCLUDES=%w{examples/company.xml
                        examples/company.rb
                        examples/company_usage.intout
+                       examples/order.xml
+                       examples/order.rb
                        examples/order_usage.intout
+                       examples/stringarray_usage.intout
+                       examples/stringarray.xml
+                       examples/documents_folders_usage.intout
+                       examples/documents_folders.xml
+                       examples/time_node_w_marshallers.intout
+                       examples/time_node_w_marshallers.xml
                        examples/time_augm.intout
+                       examples/time_augm_loading.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}
+                       examples/order_signature_enhanced_usage.intout
+                       examples/order_signature_enhanced.xml
+                       examples/person.intout
+                       examples/publication.intout
+                       examples/reader.intout
+                       examples/person_mm.intout
+                      }
 
 
 desc "Default Task"
@@ -48,6 +60,7 @@ task :default => [ :test ]
 Rake::TestTask.new(:test) { |t|
   t.test_files = ["test/all_tests.rb"]
   t.verbose = true
+#  t.loader = :testrb
 }
 
 # runs tests only if sources have changed since last succesful run of
@@ -59,10 +72,10 @@ end
 
 
 
-Rake::RDocTask.new { |rdoc|
+MyRDocTask.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.options += %w{--line-numbers --inline-source --accessor cattr_accessor=object --include examples}
   rdoc.rdoc_files.include(*FILES_RDOC_EXTRA)
   rdoc.rdoc_files.include('lib/**/*.rb')
 
@@ -139,20 +152,17 @@ 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")
+FILES_RDOC_INCLUDES.select{|f|f=~/.intout$/}.each do |f|
+  file f => FileList.new("lib/**/*.rb")
+  file f => FileList.new("examples/**/*.rb")
 end
 
+file 'examples/company_usage.intout' => ['examples/company.xml']
+file 'examples/documents_folders_usage.intout' => ['examples/documents_folders.xml']
+file 'examples/order_signature_enhanced_usage.intout' => ['examples/order_signature_enhanced.xml']
+file 'examples/order_usage.intout' => ['examples/order.xml']
+file 'examples/stringarray_usage.intout' => ['examples/stringarray.xml']
+
 
 spec = Gem::Specification.new do |s|
   s.name = 'xml-mapping'
@@ -168,12 +178,12 @@ spec = Gem::Specification.new do |s|
   s.files += Dir.glob("{lib,examples,test}/**/*").delete_if do |item|
     item.include?("CVS") || item =~ /~$/
   end
-  s.files += %w{LICENSE Rakefile ChangeLog install.rb}
+  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.autorequire = 'xml/mapping'
 
   # s.add_dependency 'rexml'
 
@@ -182,8 +192,9 @@ spec = Gem::Specification.new do |s|
   s.test_file = 'test/all_tests.rb'
 
   s.author = 'Olaf Klischat'
-  s.email = 'klischat@cs.tu-berlin.de'
+  s.email = 'olaf.klischat@sofd.de'
   s.homepage = "http://xml-mapping.rubyforge.org"
+  s.rubyforge_project = "xml-mapping"
 end
 
 
@@ -207,7 +218,7 @@ end
 
 
 task :rfpub_rdoc => [:rdoc] do
-  p=Rake::SshDirPublisher.new('xml-mapping.rubyforge.org',
+  p=Rake::SshDirPublisher.new('rubyforge.org',
                               '/var/www/gforge-projects/xml-mapping/',
                               'doc/api')
   p.upload

data/TODO.txt

@@ -1,18 +1,49 @@
-- 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...)
+- XML::XXPath: Write a real XPath parser eventually
+
+- XML::XXPath: avoid duplicates in path.all(node) result arrays when
+  using the descendants ("//") axis
+
+- invent an XPath-like language for Ruby object graphs (i.e. a
+  language that is to Ruby object graphs what XPath is to XML
+  trees). Use expressions in that language as a generalization of
+  "attribute names" (e.g. the 1st parameter to single attribute node
+  factory methods). The language could more or less be Ruby itself,
+  but the write support would need some extra work...
+
+- XML::XXPath:
+
+  - implement .[@attrname] steps
+
+    - returns the context node iff it contains an attrname attribute
+
+    - doesn't work properly in REXML::XPath?
+
+  - implement *[@attrname] steps
+
+  - implement *[@attrname='attrvalue'] steps
+
+  - id/idref support (write support possible?)
+
+- XML::Mapping: make SubObjectBaseNode a mixin instead of a subclass
+  of SingleAttributeNode ("mapping sub-objects" and "mapping to a
+  single attribute" are orthogonal concepts; inheritance is bad design
+  here)
 
 - documentation:
 
   - README:
 
-    - multi-attribute nodes
+    - document/show usage of default_when_xpath_err outside node type
+      implementations
+
+  - README_XPATH:
+
+    - mention new step types, new axes, xml/xpath_methods
 
-- XML::Mapping: Move @options hash functionality from
-  SingleAttributeNode to Node.
 
-- XML::Mapping/default attribute values: Update documentation, digest
-  "nil" issues...
+- XML::XXPath/XML::Mapping: support for XML namespaces in XML::XXPath
+  (match nodes with specific namespaces only) and XML::Mapping
+  (use_namespace etc.)
 
 - 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

data/examples/README

@@ -0,0 +1,5 @@
+This directory contains the example code snippets from the main README
+file (each time the documentation is regenerated, they're included in
+the README, executed, and their output is checked for correctness and
+included in the README as well). So, if you've read the README, you've
+already seen all the examples from this directory.

data/examples/company_usage.intout

@@ -1,11 +1,11 @@
 c = Company.load_from_file('company.xml') 
-=> #<Company:0x312dc8 @customers=[#<Customer:0x310bd8 @name="James Kirk", @id="jim">, #<Customer:0x310200 @name="Ernie", @id="ernie">, #<Customer:0x30f7f8 @name="Bert", @id="bert">], @address=#<Address:0x3123d8 @zip=10113, @city="Berlin">, @name="ACME inc.">
+=> #<Company:0x7f487635b068 @address=#<Address:0x7f487635a1e0 @zip=10113, @city="Berlin">, @name="ACME inc.", @customers=[#<Customer:0x7f48763584d0 @name="James Kirk", @id="jim">, #<Customer:0x7f4876356d88 @name="Ernie", @id="ernie">, #<Customer:0x7f4876355640 @name="Bert", @id="bert">]>
 c.name 
 => "ACME inc."
 c.customers.size 
 => 3
 c.customers[1] 
-=> #<Customer:0x310200 @name="Ernie", @id="ernie">
+=> #<Customer:0x7f4876356d88 @name="Ernie", @id="ernie">
 c.customers[1].name 
 => "Ernie"
 c.customers[0].name 
@@ -13,27 +13,39 @@ c.customers[0].name
 c.customers[0].name = 'James Tiberius Kirk' 
 => "James Tiberius Kirk"
 c.customers << Customer.new('cm','Cookie Monster') 
-=> [#<Customer:0x310bd8 @name="James Tiberius Kirk", @id="jim">, #<Customer:0x310200 @name="Ernie", @id="ernie">, #<Customer:0x30f7f8 @name="Bert", @id="bert">, #<Customer:0x30e118 @name="Cookie Monster", @id="cm">]
+=> [#<Customer:0x7f48763584d0 @name="James Tiberius Kirk", @id="jim">, #<Customer:0x7f4876356d88 @name="Ernie", @id="ernie">, #<Customer:0x7f4876355640 @name="Bert", @id="bert">, #<Customer:0x7f4876352b48 @name="Cookie Monster", @id="cm">]
 xml2 = c.save_to_xml 
 => <company name='ACME inc.'> ... </>
 xml2.write($stdout,2) 
 <company name='ACME inc.'>
-      <address>
-        <city>Berlin</city>
-        <zip>10113</zip>
-      </address>
-      <customers>
-        <customer id='1607148'>
-          <name>James Tiberius Kirk</name>
-        </customer>
-        <customer id='1605888'>
-          <name>Ernie</name>
-        </customer>
-        <customer id='1604604'>
-          <name>Bert</name>
-        </customer>
-        <customer id='1601676'>
-          <name>Cookie Monster</name>
-        </customer>
-      </customers>
-    </company>
+  <address>
+    <city>
+      Berlin
+    </city>
+    <zip>
+      10113
+    </zip>
+  </address>
+  <customers>
+    <customer id='69974598795880'>
+      <name>
+        James Tiberius Kirk
+      </name>
+    </customer>
+    <customer id='69974598792900'>
+      <name>
+        Ernie
+      </name>
+    </customer>
+    <customer id='69974598789920'>
+      <name>
+        Bert
+      </name>
+    </customer>
+    <customer id='69974598784420'>
+      <name>
+        Cookie Monster
+      </name>
+    </customer>
+  </customers>
+</company>

data/examples/documents_folders.rb

@@ -0,0 +1,31 @@
+require 'xml/mapping'
+
+class Entry
+  include XML::Mapping
+
+  text_node :name, "@name"
+end
+
+
+class Document <Entry
+  include XML::Mapping
+
+  text_node :contents, "contents"
+end
+
+
+class Folder <Entry
+  include XML::Mapping
+
+  array_node :entries, "document|folder", :default_value=>[]
+
+  def [](name)
+    entries.select{|e|e.name==name}[0]
+  end
+
+  def append(name,entry)
+    entries << entry
+    entry.name = name
+    entry
+  end
+end

data/examples/documents_folders.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<folder name="home">
+  <document name="plan">
+    <contents> inhale, exhale</contents>
+  </document>
+
+  <folder name="work">
+    <folder name="xml-mapping">
+      <document name="README">
+        <contents>foo bar baz</contents>
+      </document>
+    </folder>
+  </folder>
+
+</folder>

data/examples/documents_folders_usage.intin.rb

@@ -0,0 +1,18 @@
+#:invisible:
+$:.unshift "../lib"
+require 'documents_folders' #<=
+#:visible:
+
+root = XML::Mapping.load_object_from_file "documents_folders.xml" #<=
+root.name #<=
+root.entries #<=
+
+root.append "etc", Folder.new
+root["etc"].append "passwd", Document.new
+root["etc"]["passwd"].contents = "foo:x:2:2:/bin/sh"
+root["etc"].append "hosts", Document.new
+root["etc"]["hosts"].contents = "127.0.0.1 localhost"
+
+xml = root.save_to_xml #<=
+#:invisible_retval:
+xml.write $stdout,2