documentation, and a few author-tests

1 files changed, 100 insertions, 3 deletions

diff --git a/lib/Tree/Transform/XSLTish.pm b/lib/Tree/Transform/XSLTish.pm
index e754cd0..2176aea 100644
--- a/lib/Tree/Transform/XSLTish.pm
+++ b/lib/Tree/Transform/XSLTish.pm
@@ -6,6 +6,7 @@ use Params::Validate ':all';
 use Tree::Transform::XSLTish::Utils;
 use Tree::Transform::XSLTish::Transformer;
 use Carp::Clan qw(^Tree::Transform::XSLTish);
+use v5.8;
 
 our $VERSION='0.1';
 
@@ -40,7 +41,7 @@ sub tree_rule {
     });
 
     # TODO at least one of 'name' and 'match' must be specified
-    # TODO default priority mased on match
+    # TODO default priority based on match
 
     my $store=Tree::Transform::XSLTish::Utils::_rules_store(scalar caller);
 
@@ -117,6 +118,8 @@ Transforming an HTML document:
  use strict;
  use warnings;
 
+ engine_class 'XML::XPathEngine';
+
  default_rules;
 
  tree_rule match => 'img[@alt="pick"]', action => sub {
@@ -124,13 +127,12 @@ Transforming an HTML document:
  };
 
  package main;
- use XML::XPathEngine;
  use HTML::TreeBuilder::XPath;
 
  my $tree=HTML::TreeBuilder::XPath->new();
  $tree->parse_file('mypage.html');
 
- my $trans=HtmlTransform->new(engine=>XML::XPathEngine->new());
+ my $trans=HtmlTransform->new();
  my ($image_srce)=$trans->transform($tree);
 
 =head1 DESCRIPTION
@@ -153,6 +155,101 @@ that are compatible with the XPath engine; for example,
 L<Tree::DAG_Node::XPath> if you use L<Tree::XPathEngine>, or
 L<HTML::TreeBuilder::XPath> if you use L<XML::XPathEngine>.
 
+=head1 EXPORTS
+
+=head2 C<tree_rule>
+
+  tree_rule match => '//node_name',
+            priority => 1,
+            action => sub { ... };
+
+This is the basic fuction to declare a transformation rule; it's
+equivalent to the C<template> element is XSLT. It takes its parameters
+as a hash:
+
+=over 4
+
+=item C<match>
+
+this is equivalent to the C<match> attribute of C<template>: it
+specifies the pattern for the nodes to which this rule applies.
+
+From the L<XSLT spec|http://www.w3.org/TR/xslt.html#NT-Pattern>:
+
+I<A pattern is defined to match a node if and only if there is a
+possible context such that when the pattern is evaluated as an
+expression with that context, the node is a member of the resulting
+node-set. When a node is being matched, the possible contexts have a
+context node that is the node being matched or any ancestor of that
+node, and a context node list containing just the context node.>
+
+=item C<name>
+
+this is equivalent of the C<name> attribute of C<template>: it allows
+calling rules by name (see
+L<call_rule|Tree::Transform::XSLTish::Transformer/call_rule>)
+
+=item C<priority>
+
+this is equivalent of the C<priority> attribute of C<template>;
+currently the "default priority" as specified in the
+L<spec|http://www.w3.org/TR/xslt.html#conflict> is not implemented
+
+=item C<action>
+
+this code-ref will be called (in list context) when the rule is to be
+applied; it can return whatever you want:
+L<call_rule|Tree::Transform::XSLTish::Transformer/call_rule> will
+return the result unchanged,
+L<apply_rules|Tree::Transform::XSLTish::Transformer/apply_rules> will
+return the list of all results of all the applied rules
+
+=back
+
+The C<action> code-ref will be called (by
+L<apply_rules|Tree::Transform::XSLTish::Transformer/apply_rules> or
+L<call_rule|Tree::Transform::XSLTish::Transformer/call_rule>) with a
+L<Tree::Transform::XSLTish::Transformer> object as its only parameter.
+
+=head2 C<default_rules>
+
+This function will declare two rules that mimic the implicit rules of
+XSLT. It's equivalent to:
+
+ tree_rule match => '/', priority => 0, action => sub {$_[0]->apply_rules};
+ tree_rule match => '*', priority => 0, action => sub {$_[0]->apply_rules};
+
+=head2 C<engine_class>
+
+  engine_class 'XML::LibXML::XPathContext';
+
+This function declares that the
+L<Tree::Transform::XSLTish::Transformer> object returned by L</new>
+should use this class to build its XPath engine.
+
+=head2 C<engine_factory>
+
+  engine_factory { My::XPath::Engine->new(params=>$whatever) };
+
+This function declares that the
+L<Tree::Transform::XSLTish::Transformer> object returned by L</new>
+should call the passed code-ref to get its engine.
+
+C<engine_class $classname> is equivalent to C<engine_factory {
+$classname->new }>.
+
+=head2 C<new>
+
+Returns a L<Tree::Transform::XSLTish::Transformer> for the rules
+declared in this package.
+
+=head1 INHERITANCE
+
+L<Stylesheet import|http://www.w3.org/TR/xslt.html#import> is implented
+with the usual Perl inheritance scheme. It should even work with
+L<Class::C3>, since we use L<Class::MOP>'s C<class_precedence_list> to
+get the list of inherited packages.
+
 =head1 AUTHOR
 
 Gianni Ceccarelli <dakkar@thenautilus.net>