=head1 NAME

XML::XPathScript::Stylesheet - XPathScript's Stylesheet Writer Guide

=head1 STYLESHEET SYNTAX

An XPathScript stylesheet is written in an ASP-like format;
everything that is not enclosed within special delimiters are
printed verbatim. 

=head2 Delimiters

=head3 <% %>

Evaluates the code enclosed without printing anything.

Example:

    <% $template->set( 'foo' => { pre => 'bar' } ); %>

=head3 <%=  %>

Evaluates the code enclosed and prints out its result. 

Example:

    Author: <%= findvalue( '/doc/author@name' ) %>

=head3 <%#  %>

Comments out the code enclosed. The code will not be executed, nor
show in the transformed document.

=head3 <%~ %>

A shorthand for <%= apply_templates(  ) %>

Example:

    Author: <%~ /doc/author %>

=head3 <%- -%>, <%-= -%>, <%-~ -%>, <%-#  -%>

If a dash is added to a delimiter, all whitespaces (including carriage
returns) predeceding or following the delimiter are removed from the 
transformed document. This is useful to keep a stylesheet readable without
generating transformed document with many whitespace gaps. The dash can be 
added independently to the right and left delimiter.

Example:

    <h1>
        <%-~ /doc/title -%>
    </h1>

=head3 <!--#include file="/path/to/file" -->

Insert the content of the file into the stylesheet. The path is 
relative to the stylesheet, not the processed document.

=head1 PRE-DEFINED VARIABLES

This section describes pre-defined variables accessible from within
a XPathScript stylesheet. 

=over 

=item $template, $t, $XML::XPathScript::trans

All three variables point to the stylesheet's template. See section
L<TRANSFORMATION TEMPLATE>.

=item $XML::XPathScript::xp

The DOM of the xml document unto which the stylesheet is applied.

=item $XML::XPathScript::current

The XML::XPathScript object from which the stylesheet has been 
invoked. See the L<XML::XPathScript> manpage for a list of 
utility methods that can be called from within the stylesheet.

=back

=head1  TRANSFORMATION TEMPLATE

The transformation template defines the modification that
will automatically be brought on document elements when 
'apply_templates' is called. 

See the L<XML::XPathScript::Template> manpage for 
details on how to configure the template.

=head2 Special tags

In addition to regular tag names, three special tags can be 
used in the template: text() and comment(), that match the
corresponding nodes in the document, and '*', a catch-all tag.


=head3  text(), #text

Matches text nodes.

Note that text nodes can be assigned a special action.
See section L</action> of this manpage. 

Example:

    <%
        $template->set( 'text()' => { pre  => '\begin{comment}',
                                      post => '\end{comment}',   );
    %>

=head3  comment()

Matches comment nodes.

=head3 '*'

Matches any regular tag (that is, not comments nor text) that 
isn't explicitly matched. 

=head2 Tag Attributes

The tags' attributes define how the associated nodes
are transformed by the template. 

=head3 pre, intro, prechildren, prechild, postchild, postchildren, extro, post

Define the text to be printed around a node. All defined attributes
are outputed in the following order:

    pre
    <tag>              # if showtag == 1
    intro   
    prechildren        # if <tag> has children
    prechild           # for each child
    [ child node ]
    postchild          # for each child
    postchildren       # if <tag> has children
    extro
    </tag>             # if showtag == 1
    post

If interpolation is enabled, XPath expressions delimited 
by curly braces can be imbedded in any of these attributes. 

    $template->set( 'movie' => { 
        pre => 'title: {./@title}, year: {./year}' 
    } );

Interpolation is enabled via the XML::XPathScript object's method
L<interpolation|XML::XPathScript/interpolation>.

The expressions' delimiter can be modified 
via the XML::XPathScript object's method 
L<interpolation_regex|XML::XPathScript/interpolation_regex>.

=head3 showtag

If set to true, the original tag is printed out.

=head3 action

Dictate how the node and its children are processed. 
The allowed values are:

=over

=item $DO_SELF_AND_KIDS, DO_SELF_AND_KIDS

Process the current node and its children.

=item $DO_SELF_ONLY, DO_SELF_ONLY

Process the current node, but not its children.

=item $DO_NOT_PROCESS, DO_NOT_PROCESS

Do not process either the current node or any of its children.

=item $DO_TEXT_AS_CHILD, DO_TEXT_AS_CHILD

Only meaningful for text nodes. When this value is given, 
the processor pretends that the text is a child of the node, 
which basically means that 
C<< $t->{pre} >> and C<< $t->{post} >> will frame the text instead of
replacing it.

Example: 

    $template->( 'text()' => { pre => 'replacement text' } );
    # will transform <foo>blah</foo> 
    # into <foo>replacement text</foo>

    $template->( 'text()' => { action => $DO_TEXT_AS_CHILD,
                               pre => 'text: '   } );
    # will transform <foo>blah</foo> 
    # into <foo>text: blah</foo>

=item I<xpath expression>

Process the current node and all its children that match the xpath expression.
The XPath expression is anchored on the current node.

Example:

    # only do the children of 'foo' having their attribute 'process' 
    # set to 'yes'
    $template->set( 'foo' => { action => './*[@process = "yes"]' } );

=back

=head3 testcode

A reference to a subroutine that will be executed upon visiting 
the tag. When invoked, the subroutine is passed three parameters: the 
current node's object, a tag object holding all the attributes 
of the visited tag, and the reference to a hash of parameters given
to B<apply_templates>. Modifications to the tag object only affect 
the transformation of the current node. To change the transformation
of all subsequent tag of the same type, use the stylesheet $template 
instead.

Also, the return value of the subroutine overrides the value of
the 'action' attribute.

Example:

    <% 
        $template->set( '*' => { testcode => \&uppercase_tag } );

        sub uppercase_tag {
            my( $n, $tag, $params ) = @_;
            my $name = $params->{case} eq 'lower' ? lc $n->getName
                     : $params->{case} eq 'upper' ? uc $n->getName
                     :                              $n->getName
                     ;
            $tag->set({ pre => "<$name>",
                        post => "</$name>", });
    
            return DO_SELF_AND_KIDS;
        }
    %>

=head3 rename

Renames the tag to the given value. Implicitly sets 'showtag' to 
true.

Example:

    # change <foo abc="def">..</foo> to 
    # <bar abc="def">...</bar>
    <% $t->set( foo => { rename => 'bar' } ); %>

=head3 insteadofchildren

Is printed instead of the node's children. Does 
nothing if the node has no children. 

I<insteadofchildren> can be a scalar, or can be a a reference to
a function. In the latter case, the return value of the 
function is printed.

Note that I<insteadofchildren> acts after I<action> and I<testcode>. 
Which means that if I<testcode> 
returns B<DO_SELF_ONLY>, B<DO_NOT_PROCESS>
or an xpath expression matching none of the node's children,
I<insteadofchildren> is not triggered.

Example of use with a scalar:

    <%
        $template->set( foo => { 
            showtag => 1,
            insteadofchildren => '[ ... children ... ]',
        } );
    %>

    <%~ //foo %>        # yields '<foo>[ ... children ... ]</foo>'
                        # if the node had children, and
                        # '<foo></foo>' if not


Example if use with a function ref

    <%
        $template->set( foo => { 
            showtag => 1,
            insteadofchildren => \&count_children,
        } );

        sub count_children {
            my( $n, $t, $params ) = @_;
            my @children = $n->findnodes( 'child:*' );
            return 'node has '.@children.' children';
        }
    %>

    <%~ //foo %>        # yields '<foo>node has X children</foo>'
                        # if the node has at least 1 child 



=head1 STYLESHEET WRITING GUIDELINES

Here are a few things to watch out for when coding stylesheets.

=head2 XPath scalar return values considered harmful

XML::XPath calls such as I<findvalue()> return objects in an object
class designed to map one of the types mandated by the XPath spec (see
L<XML::XPath> for details). This is often not what a Perl programmer
comes to expect (e.g. strings and numbers cannot be treated the
same). There are some work-arounds built in XML::XPath, using operator
overloading: when using those objects as strings (by concatenating
them, using them in regular expressions etc.), they become strings,
through a transparent call to one of their methods such as 
I< ->value() >. 
However, we do not support this for a variety of reasons
(from limitations in L</overload> to stylesheet compatibility between
XML::XPath and XML::LibXML to Unicode considerations), and that is why
our L</findvalue> and friends return a real Perl scalar, in violation
of the XPath specification.

On the other hand, L</findnodes> does return a list of objects in list
context, and an I<XML::XPath::NodeSet> or I<XML::LibXML::NodeList>
instance in scalar context, obeying the XPath specification in
full. Therefore you most likely do not want to call I<findnodes()> in
scalar context, ever: replace

   my $attrnode = findnodes('@url',$xrefnode); # WRONG!

with

   my ($attrnode) = findnodes('@url',$xrefnode);


=head2 Do not use DOM method calls, for they make stylesheets non-portable

The I<findvalue()> such functions described in
L<XML::XPathScript::Processor> are not the only way of extracting bits from
the XML document. Objects passed as the first argument to the
C<testcode> tag attribute and returned by I<findnodes()> in array
context are of one of the I<XML::XPath::Node::*> or I<XML::LibXML::*>
classes, and they
feature some data extraction methods by themselves, conforming to the
DOM specification.

However, the names of those methods are not standardized even among
DOM parsers (the accessor to the C<childNodes> property, for example,
is named C<childNodes()> in I<XML::LibXML> and C<getChildNodes()> in
I<XML::XPath>!). In order to write a stylesheet that is portable
between L<XML::libXML> and L<XML::XPath> used as back-ends to
L<XML::XPathScript>, one should refrain from doing that. The exact
same data is available through appropriate XPath formulae, albeit more
slowly, and there are also type-checking accessors such as
C<is_element_node()> in L<XML::XPathScript::Processor>.

=head1 THE UNICODE MESS

Unicode is a balucitherian character numbering standard, that strives
to be a superset of all character sets currently in use by humans and
computers. Going Unicode is therefore the way of the future, as it
will guarantee compatibility of your applications with every character
set on planet Earth: for this reason, all XML-compliant APIs
(XML::XPathScript being no exception) should return Unicode strings in
all their calls, regardless of the charset used to encode the XML
document to begin with.

The gotcha is, the brave Unicode world sells itself in much the same
way as XML when it promises that you'll still be able to read your
data back in 30 years: that will probably turn out to be true, but
until then, you can't :-)

Therefore, you as a stylesheet author will more likely than not need
to do some wrestling with Unicode in Perl, XML::XPathScript or
not. Here is a primer on how.

=head2 Unicode, UTF-8 and Perl

Unicode is B<not> a text file format: UTF-8 is. Perl, when doing
Unicode, prefers to use UTF-8 internally.

Unicode is a character numbering standard: that is, an abstract
registry that associates unique integer numbers to a cast of thousands
of characters. For example the "smiling face" is character number
0x263a, and the thin space is 0x2009 (there is a URL to a Unicode
character table in L</SEE ALSO>). Of course, this means that the
8-bits- (or even, Heaven forbid, 7-bits-?)-per-character idea goes
through the window this instant. Coding every character on 16 bits in
memory is an option (called UTF-16), but not as simple an idea as it
sounds: one would have to rewrite nearly every piece of C code for
starters, and even then the Chinese aren't quite happy with "only"
65536 character code points.

Introducing UTF-8, which is a way of encoding Unicode character
numbers (of any size) in an ASCII- and C-friendly way: all 127 ASCII
characters (such as "A" or or "/" or ".", but I<not> the ISO-8859-1
8-bit extensions) have the same encoding in both ASCII and UTF-8,
including the null character (which is good for strcpy() and
friends). Of course, this means that the other characters are rendered
using I<several> bytes, for example "é" is "Ã©" in UTF-8. The result
is therefore vaguely intelligible for a Western reader.

=head2 Output to UTF-8 with XPathScript

The programmer- and C-friendly characteristics of UTF-8 have made it
the choice for dealing with Unicode in Perl. The interpreter maintains
an "UTF8-tainted" bit on every string scalar it handles (much like
what L<perlsec> does for untrusted data). Every function in
XML::XPathScript returns a string with such bit set to true:
therefore, producing UTF-8 output is straightforward and one does not
have to take any special precautions in XPathScript.

=head2 Output to a non-UTF-8 character set with XPathScript

When L</binmode> is invoked from the stylesheet body, it signals that
the stylesheet output should I<not> be UTF-8, but instead some
user-chosen character encoding that XML::XPathScript cannot and will
not know or care about. Calling C< XML::XPathScript->current()->binmode() > 
has the following consequences:

=over 2

=item *

presence of this "UTF-8 taint" in the stylesheet output is now a fatal
error. That is, whenever the result of a template evaluation is marked
internally in Perl with the "this string is UTF-8" flag (as opposed to
being treated by Perl as binary data without character meaning, see
L</perlunicode>), L<XML::XPathScript::Processor/translate_node> will
croak;

=item *

the stylesheet therefore needs to build an "unicode firewall". That
is, C<testcode> blocks have to take input in UTF-8 (as per the XML
standard, UTF-8 indeed is what will be returned by
L<XML::XPathScript::Processor/findvalue> and such) and provide output in
binary (in whatever character set is intended for the output), lest
I<translate_node()> croaks as explained above. The L<Unicode::String>
module comes in handy to the stylesheet writer to cast from UTF-8 to
an 8-bit-per-character charset such as ISO 8859-1, while laundering
Perl's internal UTF-8-string bit at the same time;

=item *

the appropriate voodoo is performed on the output filehandle(s) so
that a spurious, final charset conversion will not happen at print()
time under any locales, versions of Perl, or phases of moon.

=back


=head1 AUTHORS

Yanick Champoux <yanick@cpan.org> 
and Dominique Quatravaux <dom@idealx.com>

