--- nfo/perl/libs/XML/XUpdate/XSLT.pm	2003/05/01 23:40:32	1.4
+++ nfo/perl/libs/XML/XUpdate/XSLT.pm	2003/05/07 03:11:28	1.6
@@ -4,9 +4,17 @@
 #
 # By Andreas Motl, andreas.motl@ilo.de
 #
-#    $Id: XSLT.pm,v 1.4 2003/05/01 23:40:32 joko Exp $
+#    $Id: XSLT.pm,v 1.6 2003/05/07 03:11:28 joko Exp $
 #
 #    $Log: XSLT.pm,v $
+#    Revision 1.6  2003/05/07 03:11:28  joko
+#    updated pod: new section "References", added item to "Todo" section
+#
+#    Revision 1.5  2003/05/06 14:24:06  joko
+#    doesn't use Carp any more
+#    updated pod
+#    attempt to rewrite xml to make it more human readable using helper modules from CPAN (node indentation, etc.)
+#
 #    Revision 1.4  2003/05/01 23:40:32  joko
 #    minor update: commented debugging part
 #
@@ -25,7 +33,7 @@
 
 =head1 NAME
 
-XML::XUpdate::XSLT - A perl module for updating xml documents using XUpdate via XSLT.
+  XML::XUpdate::XSLT - A perl module for updating xml documents using XUpdate via XSLT.
 
 
 =head3 Overview
@@ -37,7 +45,7 @@
   xupdate - Process XUpdate commands against an XML document.
 
 
-=head3 Their implementations differ:
+=head4 Their implementations differ:
 
     1. xupdate (by Petr Pajas) uses ...
     XML::XUpdate::LibXML - Simple implementation of XUpdate format 
@@ -52,7 +60,7 @@
     2. This xupdate attempts to implement the XUpdate specs using XSLT only.
     
 
-=head3 Yet another xupdate - facts in short:
+=head4 Yet another xupdate - facts in short:
 
   S: It would be nice to have a pure perl thingy which does (almost) the same stuff....
   
@@ -63,15 +71,39 @@
   
   Q: Can we mimic/use the interface of the - already established - 'xupdate' program???
   
-  Q: Should we follow the CRUD path first? (CRUD means: Create, Retrieve, Update, Delete)
+  Q: Should we follow the CRUD path first?
+      (CRUD is the acronym for the datastore action primitives: Create, Retrieve, Update, Delete)
   S?: Proposal: XML::XUpdate::XSLT::API uses XML::XUpdate::XSLT::CRUD
 
 
-=head4 Todo
+=head3 References
+
+    - XUpdate:
+      Requirements: http://www.xmldb.org/xupdate/xupdate-req.html
+      Working Draft: http://www.xmldb.org/xupdate/xupdate-wd.html
+    - XML API:
+    - XML::XUpdate::LibXML: http://search.cpan.org/author/PAJAS/XML-XUpdate-LibXML-0.4.0/lib/XML/XUpdate/LibXML.pm
+    - XSL / XSLT:
+      http://www.w3.org/TR/xslt
+      http://www.xsl-rp.de/
+      http://xml.klute-thiemann.de/w3c-de/REC-xslt-20020318/
+      http://xmlxslt.sourceforge.net/
+    - misc pointers:
+      "Re: Modify XML documents": http://aspn.activestate.com/ASPN/Mail/Message/perl-xml/1265431
+      XSL Extensions: http://xmlsoft.org/XSLT/extensions.html
+      EXSLT: http://www.exslt.org/set/functions/difference/index.html
+      "how to insert element at required position in document tree?": http://p2p.wrox.com/archive/xslt/2001-06/98.asp
+      XML APIs for Databases: http://www.javaworld.com/javaworld/jw-01-2000/jw-01-dbxml.html
+
+
+=head3 Todo
 
   o What about proper encoding? (ISO-8859-1 or UTF-8)
   o Is it possible to create the required "xsl_template.xml" at runtime via XSL itself?
   o Cache contents of external files (*.xml). Performance!
+  o Can exception / error-code handling be improved somehow?
+      Esp.: It would be interesting, if the XUpdate payload actually could be applied, or not...
+  o <xupdate:if>, etc.
   
 
 =cut
@@ -84,10 +116,10 @@
 use strict;
 use warnings;
 
-use XML::XSLT 0.41;
-use Carp;
-use File::Basename;
 use Data::Dumper;
+use File::Basename;
+use XML::XSLT 0.41;
+use XML::XUpdate::Rewrite;
 
 # Namespace constants
 
@@ -156,7 +188,7 @@
 }
 
 # First, translate the xupdate payload to xsl.
-# FIXME: do DOM only!
+# FIXME: do DOM only! (don't use "->toString")
 sub _calculate {
   my $self = shift;
   $self->{XSLT_ENGINE_PREP} = XML::XSLT->new(
@@ -175,7 +207,7 @@
   my $self = shift;
   
   # debug - print the calculated xsl on STDERR
-  #print STDERR $self->get_stylesheet("_worker"), "\n";
+  print STDERR $self->get_stylesheet("_worker"), "\n";
   
   #return;
   $self->{XSLT_ENGINE_LIVE} = XML::XSLT->new(
@@ -190,19 +222,35 @@
   
 sub toString {
   my $self = shift;
-  return $self->{XML}->{result};
+  
+  # use rest of argument list as hash of option values
+  my $options = {@_};
+  
+  # short circuit - just return what we have - don't modify anything
+  return $self->{XML}->{result} unless $options and $options->{rewrite};
+  
+  # Rewrite the xml document with certain engine to desired style.
+  # 'engine' defaults to "XMLParser" if not specified.
+  my $rewrite = XML::XUpdate::Rewrite->new( style => $options->{mode}, engine => $options->{using} );
+  $rewrite->set_document( $self->{XML}->{result} );
+  # TODO: Implement a configurable fallback here to return the un-rewritten payload if desired.
+  $rewrite->process() or die(__PACKAGE__ . ": Error while rewriting XML document.");
+  return $rewrite->get_document();
 }
-
+
 
 ######################################################################
 # AUXILIARY METHODS
 
-# Argument parsing (with backwards compatibility hook).
+# Argument list parsing.
+# ... from XML::XUpdate::LibXML (w/o backwards compatibility hook).
+# Could this make up a Class::AutoFill::__read_arglist which transparently 
+# makes object attributes from constructor arguments in a configurable way?
 sub __parse_args {
   my $self = shift;
   my %args;
 
-  if(@_ % 2 ) {
+  if ( @_ % 2 ) {
     $args{dummy} = shift;
     %args = (%args, @_);
   } else {
@@ -228,7 +276,7 @@
   if (! -e $filename) {
     $filename = dirname(__FILE__) . "/$filename";
     if (! -e $filename) {
-      croak("File $filename does not exist.");
+      die("File $filename does not exist.");
     }
   }