pdf-labels 1.0.0

data/vendor/xml-mapping/README_XPATH

@@ -0,0 +1,175 @@
+= XML-XXPATH
+
+== Overview, Motivation
+
+Xml-xxpath is an (incomplete) XPath interpreter that is at the moment
+bundled with xml-mapping. It is built on top of REXML. xml-mapping
+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
+"/foo/bar[3]/baz[@key='hiho']" to the XML document
+
+  <foo>
+    <bar>
+      <baz key='ab'>hello</baz>
+      <baz key='xy'>goodbye</baz>
+    </bar>
+  </foo>
+
+, you'll get:
+
+  <foo>
+    <bar>
+      <baz key='ab'>hello</baz>
+      <baz key='xy'>goodbye</baz>
+    </bar>
+    <bar/>
+    <bar><baz key='hiho'/></bar>
+  </foo>
+
+This feature is used by xml-mapping when writing (marshalling) Ruby
+objects to XML, and is actually the reason why I couldn't just use any
+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 :)
+
+Some basic knowledge of XPath is helpful for reading this document (I
+don't know very much either).
+
+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:
+
+- a simple element name _name_, e.g. +signature+
+
+- an attribute name, @_attr_name_, e.g. <tt>@key</tt>
+
+- a combination of an element name and an attribute name and
+  -value, in the form _elt_name_[@_attr_name_='_attr_value_']
+
+- an element name and an index, _elt_name_[_index_]
+
+- the "match-all" path element, <tt>*</tt>
+
+
+== Usage
+
+Xml-xxpath defines the class XML::XXPath. An instance of that class
+wraps an XPath expression, the string representation of which must be
+supplied when constructing the instance. You then call instance
+methods like _first_, _all_ or <i>create_new</i> on the instance,
+supplying the REXML Element the XPath expression should be applied to,
+and get the results, or, in the case of write access, the element is
+updated in-place.
+
+
+=== Read Access
+
+  :include: xpath_usage.intout
+
+The objects supplied to the <tt>all()</tt>, <tt>first()</tt>, and
+<tt>each()</tt> calls must be REXML element nodes, i.e. they must
+support messages like <tt>elements</tt>, <tt>attributes</tt> etc
+(instances of REXML::Element and its subclasses do this). The calls
+return the found elements as instances of REXML::Element or
+XML::XXPath::Accessors::Attribute. The latter is a wrapper around
+attribute nodes that is largely call-compatible to
+REXML::Element. This is so you can write things like
+<tt>path.each{|node|puts node.text}</tt> without having to
+special-case anything even if the path matches attributes, not just
+elements.
+
+As you can see, you can re-use path objects, applying them to
+different XML elements at will. You should do this because the XPath
+pattern is stored inside the XPath object in a pre-compiled form,
+which makes it more efficient.
+
+The path elements of the XPath pattern are applied to the
+<tt>.elements</tt> collection of the passed XML element and its
+sub-elements, starting with the first one. This is shown by the
+following code:
+
+  :include: xpath_docvsroot.intout
+
+A REXML +Document+ object is a REXML +Element+ object whose +elements+
+collection consists only of a single member -- the document's root
+node. The first path element of the XPath -- "foo" in the example --
+is matched against that. That is why the path "/bar" in the example
+doesn't match anything when matched against the document +d+ itself.
+
+An ordinary REXML +Element+ object that represents a node somewhere
+inside an XML tree has an +elements+ collection that consists of all
+the element's direct sub-elements. That is why XPath patterns matched
+against the +firstelt+ element in the example *must not* start with
+"/first" (unless there is a child node that is also named "first").
+
+
+=== Write Access
+
+You may pass a <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
+option argument. If the path didn't exist before, the XML element is
+modified such that
+
+- the path exists afterwards
+
+- all paths that existed before still exist afterwards
+
+- the modification is as small as possible (i.e. as few elements as
+  possible are added, additional attributes are added to existing
+  elements if possible etc.)
+
+The created resp. previously existing, matching elements are returned.
+
+
+Examples:
+
+  :include: xpath_ensure_created.intout
+
+
+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
+exception raised if that wasn't possible for any path element).
+
+Examples:
+
+  :include: xpath_create_new.intout
+
+
+=== Pathological Cases
+
+What is created when the Path "*" is to be created inside an empty XML
+element? The name of the element to be created isn't known, but still
+some element must be created. The answer is that xml-xxpath creates a
+special "unspecified" element whose name must be set by the caller
+afterwards:
+
+  :include: xpath_pathological.intout
+
+The "newelt" object in the last example is an ordinary
+REXML::Element. xml-xxpath mixes the "unspecified" attribute into that
+class, as well as into the XML::XXPath::Accessors::Attribute class
+mentioned above.
+
+
+== Implentation notes
+
+<tt>doc/xpath_impl_notes.txt</tt> contains some documentation on the
+implementation of xml-xxpath.
+
+== License
+
+Ruby's.

data/vendor/xml-mapping/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 ChangeLog 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/vendor/xml-mapping/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/vendor/xml-mapping/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
+              }